@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.
• Expose additional atomic external API tools for extended scenarios without making the primary import/export flow heavier.

Requirements

• An MCP client that supports stdio servers.
• A working JavaScript runtime that can launch the server via npx or bunx.
• 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 for file-oriented import/export flows (relative path such as "./" or "./apps/web")

Notes:

• The additional atomic external API tools can work without targetProjectPath.
• The primary file-oriented import/export tools still require targetProjectPath.

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.

Targeted block-level transfer:

Inspect PrimeUI page /pricing, then copy the block with blockId pricing-hero-2 and componentId hero--split into my project.

Tools

PrimeUI MCP has two tool groups:

1. Primary import/export flow tools. These are the default tools for page-by-page imports into a local codebase.
2. Additional atomic external API tools. These are optional endpoint-aligned capabilities for extended scenarios and do not replace the primary flow.

Primary import/export flow 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? | | copy_component | Safely copies one canonical component file for a selected block instance, adds missing package dependencies, returns exact block props plus occurrenceIndex / contentKey, and reports page-level follow-up files only as hints. | originPageSlug, blockId, componentId, projectRoot? | | copy_exportable | Safely copies one shared exportable from downloaded export into user project using only export.exportables[].manifest.files, returns not_available for disabled exportables, and reports missedDependencies instead of copying package.json. | exportableKey, projectRoot? | | clear_temp | Clears .primeui/temp/ and recreates baseline temp layout. | projectRoot? |

Additional atomic external API tools

These tools map one-to-one to newer external API endpoints. They are independent operations for advanced or secondary scenarios. They must not be treated as a required chain and they do not replace the standard import/export workflow.

| Tool | What it does | Input | | -------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | project_description_get | Returns the current shared project description. | projectRoot? | | project_description_upsert | Creates, updates, or clears the shared project description. | projectDescription, projectRoot? | | project_pages_list | Returns the current page inventory with lightweight variant summaries. | projectRoot? | | project_page_get | Returns one page by pageId using the same page envelope as the list endpoint. | pageId, projectRoot? | | project_page_create | Creates a new page and its initial variant. | slug, title, pageType, contentMode, componentIds?, prompt?, projectRoot? | | project_page_variants_list | Returns lightweight variant summaries for one page. | pageId, projectRoot? | | project_page_variant_get | Returns one variant with its component payload. | pageId, variantId, projectRoot? | | project_page_variant_create | Creates one new variant for an existing page. | pageId, name?, contentMode, componentIds?, prompt?, projectRoot? | | project_page_active_variant_set| Sets the export-selected active variant for one page. | pageId, variantId, projectRoot? | | project_issue_report_submit | Submits an issue report for the scoped project. | reportText, tags?, 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"
      }
    }
  }
}

Verified bunx CLI alternative for direct invocation:

bunx --package @primeuicom/mcp@latest primeui-mcp --version
bunx --package @primeuicom/mcp@latest primeui-mcp --health

Notes:

• Use the explicit binary form with --package ... primeui-mcp.

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, copy_page, copy_component, and copy_exportable always validate project config before running any mutation.
• The additional atomic external API tools use the same project config and API key resolution, but they do not depend on .primeui/temp/, the export manifest flow, or targetProjectPath validation.
• The file-oriented import/export tools still require a valid targetProjectPath because they operate on the linked local target project.
• 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