@xpmetric/mcp

MCP server for XPmetric. Pull traffic and revenue into your editor, and create conversion goals and funnels against the same /api/v1 surface as the dashboard — while the agent has your checkout code open.

A goal only fires if window.xpmetric('event_name') exists in the page. The agent can add that call and create the matching goal in one turn.

Remote HTTP MCP is not supported. This package speaks stdio only — it is the xpmetric-mcp bin, not an importable library.

Setup

1. Open Settings → General → API keys at xpmetric.com, name a key, and copy it once. The prefix is xpm_mcp_. A key covers every site on the account.
2. Add the server to your editor (snippets below).
3. Restart the MCP session.

Environment

| Variable | Required | Default | |---|---|---| | XPMETRIC_API_KEY | yes | — | | XPMETRIC_BASE_URL | no | https://xpmetric.com |

Point XPMETRIC_BASE_URL at http://127.0.0.1:3000 or http://localhost:<port> for local development. Any other host is rejected so the API key is never forwarded elsewhere.

Claude Code

{
  "mcpServers": {
    "xpmetric": {
      "command": "npx",
      "args": ["-y", "@xpmetric/mcp"],
      "env": {
        "XPMETRIC_API_KEY": "xpm_mcp_YOUR_KEY"
      }
    }
  }
}

Cursor

Add the same block under Cursor Settings → MCP (or .cursor/mcp.json):

{
  "mcpServers": {
    "xpmetric": {
      "command": "npx",
      "args": ["-y", "@xpmetric/mcp"],
      "env": {
        "XPMETRIC_API_KEY": "xpm_mcp_YOUR_KEY"
      }
    }
  }
}

Local checkout

For local development against a checkout, build once and point the editor at the compiled bin:

cd packages/mcp
npm install
npm run build

{
  "mcpServers": {
    "xpmetric": {
      "command": "node",
      "args": ["/ABS/PATH/TO/xpmetric/packages/mcp/dist/index.js"],
      "env": {
        "XPMETRIC_API_KEY": "xpm_mcp_YOUR_KEY",
        "XPMETRIC_BASE_URL": "http://127.0.0.1:3000"
      }
    }
  }
}

npx from that directory also works after a build: npx xpmetric-mcp (requires XPMETRIC_API_KEY).

CI

GitHub Actions workflow .github/workflows/mcp.yml runs npm ci && npm test && npm run build on every PR and main push that touches packages/mcp/**. It is independent of the production Docker deploy pipeline.

Tools

| Tool | Purpose | |---|---| | list_sites | Sites on the key (id, domain, trackingMode) — start here | | get_stats | Period totals (visitors, pageviews, bounce, session time, revenue, compare) | | get_timeseries | Bucketed traffic series | | get_breakdown | Ranked breakdown for one dimension (dim = path, country, channel, …) | | discover_goal_candidates | Custom events firing with no goal yet | | get_tracking_snippet | Guarded window.xpmetric('event') snippet to paste into the repo | | list_goals / create_goal / update_goal / delete_goal | Goal CRUD | | list_funnels / create_funnel / update_funnel / delete_funnel / get_funnel_data | Funnel CRUD + data |

Public install docs: xpmetric.com/docs/mcp-server. This server never writes the user's files.

License

MIT