MCP server

The CLI includes a Model Context Protocol server for React Native and Expo projects. Native Animation Base is free forever, MIT licensed, and needs no account. Its setup, discovery, docs, and installation tools work anonymously. Other catalog pieces keep their own account and license requirements; adding those pieces requires a signed-in account with access, including non-Base free pieces.

Connect the MCP. Build the whole app.

The server runs locally over stdio through the CLI. It needs Node 20 or later. Your client starts it for you.

Claude Code

claude mcp add nativeanimation -- npx -y nativeanimation@latest mcp

Codex

codex mcp add nativeanimation -- npx -y nativeanimation@latest mcp

Cursor and Windsurf

Cursor, Windsurf and other clients take the same command in their MCP settings (in Cursor, .cursor/mcp.json):

{
  "mcpServers": {
    "nativeanimation": { "command": "npx", "args": ["-y", "nativeanimation@latest", "mcp"] }
  }
}

VS Code

VS Code uses a servers key in .vscode/mcp.json:

{
  "servers": {
    "nativeanimation": { "type": "stdio", "command": "npx", "args": ["-y", "nativeanimation@latest", "mcp"] }
  }
}

Official registry

The server is listed in the official MCP Registry as com.nativeanimation/nativeanimation.

Base works without an account

Read the nativeanimation://base/guide resource or use the build-app-with-base prompt to plan a complete app. Browse components with list_family and complete screens with list_blocks. Use setup_base to review a theme and layout plan, then apply it with apply: true. Install MIT Base source and its dependency closure with add_block or add_piece, without a session. get_piece reads public documentation, and search_pieces searches the catalog without a session. Base is also available by manual download from each component page and in the public source repository.

Add other catalog pieces

Searching, reading docs, and installing Base work without an account. To add other catalog pieces, sign in once from a terminal:

Your agent will never sign in or buy for you. Without a session it can set up and install Base, search and read public documentation, or copy free source.

Tools

add_piece never overwrites files that differ unless the agent passes overwrite, only writes inside your project, and leaves dependency installs to the agent unless it asks for them. If your MCP client starts servers outside the project folder, the agent passes the absolute project path in project_root. The destination must be an Expo project. Identical files are left untouched.

Search and choose a piece

No login is needed to search or read docs. Without an MCP client, use nativeanimation search "loading button" and nativeanimation show <id> --json in your terminal; see CLI.

search_pieces accepts natural-language intents such as "a button that shows progress then success", plus tag, free_only, limit (default 10, maximum 20), cursor and exclude_dependencies (a hard filter of package names). Examples:

{"query":"a button that shows progress then success","limit":5}

{"query":"bottom sheet with blur","exclude_dependencies":["@shopify/react-native-skia"]}

The tool declares an outputSchema. Its structuredContent includes query, normalized_query, truncated, total, returned, next_cursor (null at the end), catalog_version, signed_in, pieces, suggestions, and next_steps (empty when there are results; otherwise list_blocks and list_family to browse anonymous Base options). Search processes the first 120 characters and 12 distinct significant concepts, including exclusions. Excess input is ignored deterministically: truncated is true when input is shortened, and false otherwise. Both query echoes are bounded to the processed input (at most 120 characters). CLI JSON uses the same contract. Pages may return fewer pieces than limit to keep the complete MCP search response under 25 KB; next_cursor continues from the last delivered piece without skipping results. without/no/not/sin/excluding/except support package exclusions and coordinated lists such as “without Skia and Reanimated” and “no blur or haptics”. Other negated words exclude title, tag, or summary matches; an exclusion absent from the snapshot vocabulary conservatively returns no results. Explicit filters remain hard constraints.

No results include up to five vocabulary-based retry queries and recommend list_blocks and list_family for anonymous Base options; successful searches have empty suggestions and next steps arrays. An empty query returns ten pieces in catalog order plus facets.types and facets.tags, arrays of { "value": "…", "count": 12 } counted over all matching pieces. Types include every type; tags show the top 20 by frequency with alphabetical ties.

Each candidate includes id, title, summary, editorial type, tags, price (USD text or free), price_cents, dependencies (package names), expo_sdk, platforms, matched, preview_video and page. Match evidence has up to eight field/term pairs, such as { "field": "title", "term": "button" }; terms are normalized literal, alias or typo alternatives present in that field (ignoring stopwords for phrases), not confidence scores. Signed-in MCP calls also show has_access. Always call get_piece before using props; search does not return them. The text block contains the same JSON for older clients. Complete search responses stay under 25 KB through byte-limited pagination, counting both the text and structured content.

Pass next_cursor with the same query and filters for the next page. Cursors are stable for a catalog version; a different query, filters or version produces a readable error. Start a new search after a version change. The page size can change between requests.

Protocol versions

The server supports MCP 2026-07-28 (stateless discovery) and the earlier initialize-based revisions: 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.

Resources and prompts

Troubleshooting

If your coding agent cannot add an animation, check your session and the project's absolute path. See My coding agent cannot add animations and the other fixes in Troubleshooting.