Pluma MCP Server

Model Context Protocol (MCP) server for accessing Pluma design system components and documentation.

🚀 Quick Start

Running in Cursor

To use this MCP server in Cursor, add the following configuration to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "pluma": {
      "command": "pnpm",
      "args": ["dlx", "@customerio/pluma-mcp@latest"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here",
        "NPM_CONFIG_USERCONFIG": "/path/to/your/.npmrc"
      }
    }
  }
}

Environment Variables:

• GITHUB_TOKEN: Required for accessing private repositories (if applicable)
• NPM_CONFIG_USERCONFIG: Path to your .npmrc file for package registry authentication

Claude Code

To use this MCP server in Claude Code, add the following to your ~/.claude.json:

"mcpServers": {
  "pluma": {
    "command": "pnpm",
    "args": [
      "dlx",
      "@customerio/pluma-mcp@latest"
    ],
    "env": {
      "GITHUB_TOKEN": "${GITHUB_TOKEN}",
      "NPM_CONFIG_USERCONFIG": "/path/to/your/.npmrc"
    }
  }
}

Environment Variables:

• GITHUB_TOKEN: Required for accessing private repositories (if applicable)
• NPM_CONFIG_USERCONFIG: Path to your .npmrc file for package registry authentication

Reporting gaps

The report_gap tool reports that Pluma fell short of what an agent needed. Its description tells the agent to call it the moment it finds no component, variant or prop for what it is building, or hits a layout, styling, accessibility, docs or API gap, before it writes a workaround.

The report goes to the handlers listed under gapReport in pluma.config.mjs in the server's working directory, the same file and handlers pluma-cli report-gap uses; see pluma.config.mjs in the @customerio/pluma-cli README for the file, the report format and the built-in handlers. With no handler configured, the report is appended to .pluma/gap-reports.jsonl at the root of the repository that holds file (the nearest directory up from it that holds a .git), or of the server's working directory without one, and the tool points the agent at the package's issue tracker. Agents should pass file as an absolute path.

The tool returns the receipt: one delivery per handler and an overall status of filed, partial, failed, routed_only or consent_required, derived as the CLI README describes.

{
  "status": "routed_only",
  "deliveries": [
    {
      "handler": "fallback",
      "audience": "internal",
      "status": "routed_only",
      "url": "https://example.com/pluma/issues",
      "message": "No gap report handler is configured. Saved to /Users/me/code/app/.pluma/gap-reports.jsonl; file it at https://example.com/pluma/issues."
    }
  ]
}

The server bundles the report format, config loader, handlers and delivery from @customerio/pluma-cli/gap-report, so building it builds the CLI first.

🛠️ Development

Setup

1. Clone the repository and navigate to the MCP package:

   cd packages/mcp

2. Install dependencies:

   pnpm install

3. Build the project:

   pnpm run build

Development Workflow

1. Build the component manifest and component data:

   pnpm run build:manifest    # Build @customerio/pluma-components/manifest (needs the components build)
   pnpm run build:components  # Generate component data from the manifest

2. Full build:

   pnpm run build  # Runs prebuild + TypeScript compilation

3. Quick development build:

   pnpm run build:fast  # Skip the data builds, just compile TypeScript

4. Run in development mode:

   pnpm run dev

5. Type checking:

   pnpm run typecheck

Testing

pnpm test                    # Run tests
pnpm run test:with-build     # Build then test
pnpm run test:with-fast-build # Fast build then test

🔍 Testing with MCP Inspector

The MCP Inspector is a great tool for testing your MCP server during development.

Test Locally Built Server

1. Build the server:

   pnpm run build

2. Run the inspector with your local build:

   pnpm dlx @modelcontextprotocol/inspector node dist/index.js

Test Published Package

mcp-inspector pnpm dlx @customerio/pluma-mcp@latest

The inspector will open a web interface where you can:

• View available tools
• Test tool calls interactively
• Inspect server responses
• Debug any issues