@runsnative/mcp-server

RunsNative MCP server — gives any MCP-capable agent access to RunsNative component docs, foundations, design exercises, and theme inference.

Docs content comes from the RunsNative cloud content API by default — no clone or configuration required, and content updates propagate without reinstalling. Developers working in the runsnative repo can set RUNSNATIVE_CONTENT_ROOT to serve from a local checkout instead.

Quick install

Add one block to your MCP client config. No environment configuration is needed.

Claude Desktop

macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
Windows — %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "runsnative": {
      "command": "npx",
      "args": ["-y", "@runsnative/mcp-server"]
    }
  }
}

Claude Code / Cursor (project-scoped)

Add .mcp.json to your project root:

{
  "mcpServers": {
    "runsnative": {
      "command": "npx",
      "args": ["-y", "@runsnative/mcp-server"]
    }
  }
}

To serve from a local checkout instead of the cloud API, add an env block:

"env": { "RUNSNATIVE_CONTENT_ROOT": "/path/to/runsnative/content" }

Authoring skill

Once the MCP server is connected, load the RunsNative authoring skill to give your agent full component-authoring guidance. The skill is served at:

https://runsnative.org/ai/authoring-skill

Paste that URL into Claude's "Add custom skill" dialog, or add it to your agent's system prompt as a skill reference. The MCP tools and the authoring skill work together — the skill tells the agent how to author; the tools give it the live content.

Tools provided

| Tool | Description | |---|---| | list_components | List all available RunsNative components | | get_component | Fetch usage, style, code, or accessibility docs for a component | | list_composition_patterns | List composition patterns (recipes) for complete UI surfaces — sign-in form, dashboard shell, chat room, etc. | | get_composition_pattern | Fetch the full pattern for a named recipe: preview spec, framework code examples, accessibility notes, customization guidance | | get_foundation | Fetch a specific foundation doc | | get_step | Fetch a specific step within an exercise | | search_docs | Semantic search across all RunsNative docs | | list_exercises | List available design exercises | | start_exercise | Start a design exercise | | infer_theme | Infer a RunsNative theme from a URL or description | | infer_brand_theme | Infer a theme from brand imagery | | surface_preview | Render a component fixture inside an MCP App iframe (RUN-477 sandbox verification, not a production surface) |

Environment variables

| Variable | Default | Description | |---|---|---| | RUNSNATIVE_API_URL | https://api.runsnative.org/mcp | Override the content API base URL (e.g. point at wrangler dev locally) | | RUNSNATIVE_CACHE_DIR | ~/.runsnative/cache | Override the local content cache directory | | RUNSNATIVE_CONTENT_ROOT | (unset) | Set to use local content instead of the cloud API. For developers working in the RunsNative repo | | RUNSNATIVE_TENANT_TOKEN | (unset) | Bearer token for tenant-specific content access |

Requirements

• Node.js 18 or later

For RunsNative repo developers

If you're working inside the RunsNative repo, use the .mcp.json at the repo root. It points at packages/mcp-server/dist/index.js directly and sets RUNSNATIVE_CONTENT_ROOT so you get live content from your working tree without hitting the cloud API.

Build first:

cd packages/mcp-server && npm run build