@primeuicom/mcp

PrimeUI MCP connects AI agents to PrimeUI so they can discover project pages, create exports, download export artifacts, and automate PrimeUI-powered workflows directly from your coding environment.

Purpose and goals

PrimeUI MCP is the integration layer between PrimeUI and MCP-compatible agents.

Core goals:

• Give agents a reliable way to read PrimeUI project metadata and page inventory.
• Let agents trigger and monitor PrimeUI exports.
• Let agents download export bundles into a local workspace for code-level operations.
• Provide a stable MCP tool contract for PrimeUI workflows.

Requirements

• An MCP client that supports stdio servers.
• A working Node.js runtime (the server is launched via npx).
• A valid PrimeUI API key (PRIMEUI_API_KEY).
• API key format: pui_<22-char-base64url>.

PrimeUI API KEY

• PrimeUI provides this key together with the exported project.
• In linked/exported projects, the key is stored in .primeui/project.json under apiKey.
• PrimeUI MCP loads PRIMEUI_API_KEY from env first, then falls back to .primeui/project.json.
• .primeui/project.json must include:
  • projectId
  • apiKey
  • targetProjectPath (required, relative path such as "./" or "./apps/web")

Your first prompts

Try this in your MCP-enabled agent:

Use PrimeUI MCP to get my project info, list pages that are ready to export. Compare them with my current pages

Next step:

Export [X page | XX pages] from PrimeUI and add them to my project.

Targeted page inspection:

Inspect PrimeUI page /pricing components and compare them with my local /pricing page.

Tools

Available tools:

| Tool | What it does | Input | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | get_project_info | Returns project metadata and page list, including export readiness and source paths. | projectRoot? | | inspect_page | Returns details for one page by slug, raw active-variant components (or null), and a formatted component report table for local comparison. | pageSlug, projectRoot? | | list_exports | Lists existing exports with ID, status, and creation time. | projectRoot? | | create_export | Starts a new export and returns strict API manifest payload (pages[].manifest.files + export.exportables), then saves sidecar manifest .primeui/temp/exports/<exportId>.manifest.json. | projectRoot? | | download_export | Downloads and extracts a completed export into .primeui/temp/exports/<exportId>/ and validates existing local sidecar manifest for this export ID. | id (export ID), projectRoot? | | copy_page | Safely copies one page from downloaded export into user project using only pages[].manifest.files (compact file lists + lightweight conflicts; full diffs saved to local copy report file). | originPageSlug, projectRoot? | | clear_temp | Clears .primeui/temp/ and recreates baseline temp layout. | projectRoot? |

Getting started

The setup below works in any MCP client that supports .mcp.json with stdio command servers (for example: Codex CLI, Cursor, Cline, and other compatible clients).

Create or update .mcp.json:

{
  "mcpServers": {
    "primeui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@primeuicom/mcp@latest"],
      "env": {
        "PRIMEUI_API_KEY": "your-primeui-api-key"
      }
    }
  }
}

Install in common MCP clients

If your CLI command syntax differs by client version, use the JSON config from Getting started with the same primeui server block.

Use the Codex MCP add command to install MCP globally:

codex mcp add primeui -- npx -y @primeuicom/mcp@latest

Add the server:

claude mcp add primeui -- npx -y @primeuicom/mcp@latest

Then configure server environment variables (at minimum PRIMEUI_API_KEY).

Add the same server config to your Cursor MCP configuration:

{
  "mcpServers": {
    "primeui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@primeuicom/mcp@latest"],
      "env": {
        "PRIMEUI_API_KEY": "your-primeui-api-key"
      }
    }
  }
}

If your setup supports VS Code MCP server registration via CLI:

code --add-mcp '{"name":"primeui","command":"npx","args":["-y","@primeuicom/mcp@latest"],"env":{"PRIMEUI_API_KEY":"your-primeui-api-key"}}'

If your setup uses JSON config instead, use the same .mcp.json example from Getting started.

Use the same .mcp.json server block from Getting started and provide PRIMEUI_API_KEY.

Add PrimeUI MCP:

gemini mcp add primeui npx -y @primeuicom/mcp@latest

Then configure PRIMEUI_API_KEY for that server entry.

Use the same JSON server configuration shown in Getting started:

{
  "mcpServers": {
    "primeui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@primeuicom/mcp@latest"]
    }
  }
}

Runtime behavior

• PrimeUI MCP uses bearer authentication with PRIMEUI_API_KEY.
• --help, --version, and --health do not start the MCP server.
• If PRIMEUI_API_KEY env is missing, PrimeUI MCP reads .primeui/project.json (apiKey).
• Server startup does not require .primeui/project.json; project config is resolved lazily per tool call.
• Config lookup order on each tool call:
  • projectRoot tool input (if provided),
  • sticky in-process root resolved by prior successful tool call,
  • PRIMEUI_PROJECT_ROOT env,
  • upward search for .primeui/project.json from current working directory.
• If config cannot be resolved, the tool returns a transparent error with actionable hint to pass projectRoot.
• clear_temp and copy_page always validate project config before running any mutation.
• Missing or invalid targetProjectPath is treated as a configuration error.
• Downloaded archives are validated as ZIP payloads before extraction.
• create_export is the source of truth for local sidecar manifest creation in .primeui/temp/exports/<exportId>.manifest.json.
• Temporary export files are written under .primeui/temp/ in user project folder.

CLI behavior

PrimeUI MCP has three execution modes:

• npx @primeuicom/mcp@latest starts the MCP stdio server for use by an MCP-compatible client.
• npx @primeuicom/mcp@latest --help prints CLI help and exits.
• npx @primeuicom/mcp@latest --version prints the package version and exits.
• npx @primeuicom/mcp@latest --health prints runtime diagnostics and exits.
• npx @primeuicom/mcp@latest --health /absolute/project/path runs the same diagnostics against an explicit project root.

Examples:

npx @primeuicom/mcp@latest --help
npx @primeuicom/mcp@latest --version
npx @primeuicom/mcp@latest --health
npx @primeuicom/mcp@latest --health /absolute/project/path

Normal MCP client configuration should launch @primeuicom/mcp without --help, --version, or --health.

Local development and testing

Configure these environment variables for local development:

• PRIMEUI_API_BASE_URL: PrimeUI API base URL (for example http://localhost:3020 when testing against local Studio API).
• PRIMEUI_PROJECT_ROOT: explicit project root override for .primeui/project.json and .primeui/temp/ location.

tip to add it to codex globally use:

codex mcp add primeui --env PRIMEUI_API_BASE_URL=http://localhost:3020 -- npx -y @primeuicom/mcp@latest

Run MCP Inspector:

pnpm inspect

This runs @modelcontextprotocol/inspector against tsx src/service.ts. After startup, open the local Inspector URL shown in the terminal (for example http://127.0.0.1:<port>) and interact with the PrimeUI MCP tools from the browser UI.

Main scripts:

• pnpm dev: run the MCP server locally via tsx src/service.ts.
• pnpm test: run unit tests with Vitest.
• pnpm typecheck: run TypeScript type checks without emitting build artifacts.
• pnpm build: clean dist/, bundle the MCP server with tsup, and mark dist/service.js executable.
• pnpm prepack: run build before packaging/publishing.

Publish

Publish flow includes:

1. Update the package version (usually a patch bump).
2. Publish with the latest tag:

npm publish --tag latest

Credits

PrimeUI 2026