@clamp-sh/mcp

Analytics MCP server for Clamp Analytics. Gives Claude, Cursor, VS Code Copilot, Windsurf, Cline, and any other Model Context Protocol client live access to your traffic, pages, events, revenue, errors, funnels, cohorts, and alerts — and the tools to create funnels and metric alerts from the conversation.

Using Cursor, VS Code, Claude Code, or Claude Desktop? Install the hosted Remote MCP from your Clamp dashboard in one click — auth happens automatically, no API key to paste, no config files to edit. Open a project, go to the Installation tab, and pick your editor. This npm package is the stdio path for CI, headless agents, custom clients, and self-hosted Clamp instances.

What your agent can do

Once connected, your agent can answer questions like:

• "How's traffic this week?"

• "Why did pageviews drop on Tuesday?"

• "Which referrers drove the most signups?"

• "Compare US vs Germany conversion this month"

• "Create a funnel from /pricing to signup to purchase"

• "Alert me when bounce rate on /pricing goes above 70%"

• "What did Hacker News visitors actually read?"

• "Run the weekly report"

Each question maps to one or two MCP tool calls. The agent picks the right tool, runs the query, and returns the answer in chat — no dashboard tab, no copy-paste.

Related MCP server: Google Analytics MCP Server

Why an MCP server for analytics

A dashboard answers the questions you anticipated when you built it. An MCP server lets the agent answer the ones you didn't. Same data, different access pattern: the agent can compose tools, follow up on its own answers, and run the diagnostic queries you'd manually click through.

Tools are typed (outputSchema per MCP protocol 2025-06-18), so client-side validation works before any call lands. Per-tool descriptions name the use case and a representative example, so agents pick the right tool on the first try.

Setup

For one-click install in Cursor / VS Code / Claude Code / Claude Desktop, use the Clamp dashboard. For stdio (CI, headless agents, custom clients, self-hosted instances), pick your client below.

VS Code / Copilot

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "clamp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@clamp-sh/mcp"],
      "env": {
        "CLAMP_API_KEY": "sk_proj..."
      }
    }
  }
}

Claude Code

claude mcp add clamp -- npx -y @clamp-sh/mcp
export CLAMP_API_KEY="sk_proj..."

Claude Desktop and Cursor

Both clients use the same shape — drop this into claude_desktop_config.json or .cursor/mcp.json:

{
  "mcpServers": {
    "clamp": {
      "command": "npx",
      "args": ["-y", "@clamp-sh/mcp"],
      "env": {
        "CLAMP_API_KEY": "sk_proj..."
      }
    }
  }
}

API key

Get your API key from the Clamp dashboard under Settings → API Keys. Keys are scoped to a project and start with sk_proj.

Tools

Free (all plans)

Pro

Common parameters

period — "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD". Defaults to "30d".

limit — Max rows returned, 1-50. Defaults to 10.

Filters — Most tools accept pathname, referrer_host, channel, country, region, city, device_type, browser, browser_version, os, os_version, and the full UTM set (utm_source, utm_medium, utm_campaign, utm_content, utm_term). Funnels accept the same cohort filters.

dimension (breakdown only) — see the breakdown row above for valid values.

view (pages.engagement only) — "summary" (default), "engagement", or "sections". "sections" requires pathname.

Revenue filters (revenue.sum, revenue.timeseries) — plan and product filter to one subscription tier or one-time product. first_touch_dim (one of channel, referrer_host, utm_campaign, utm_source, utm_medium, country) + first_touch_value filter to customers whose earliest session matched that dim. attribution_model="first_touch" on revenue.sum groups by first-touch dim instead of conversion-time dim.

Revenue metric (revenue.timeseries only) — "revenue" (default), "mrr" (running balance), "customers", or "transactions".

Prompts

Pre-built analytics workflows the AI can follow. Each prompt tells the model which tools to call, in what order, and how to present the results.

Examples

Traffic overview

"How's my traffic this week?"

Calls traffic.overview with period="7d". Returns pageviews, visitors, sessions, bounce rate, avg duration, and comparison to the previous week.

"Show me visitor trends for the last 90 days"

Calls traffic.timeseries with period="90d" and metric="visitors". Returns daily counts over the full window.

Sources and geography

"Where are my visitors coming from?"

Calls breakdown with dimension="referrer_host". Returns referrer hostnames with channel classification (organic_search, direct, referral, paid, email, organic_social) joined into each row.

"Which cities in Germany have the most visitors?"

Calls breakdown with dimension="city" and country="DE". Returns city names with country and visitor/pageview counts.

"Is Safari 17 bouncing harder than Chrome 120?"

Two calls to traffic.overview with browser="Safari", browser_version="17" and browser="Chrome", browser_version="120". Returns side-by-side bounce rates.

"Which pages did Hacker News visitors read?"

Calls pages.engagement with referrer_host="news.ycombinator.com". Returns only pages viewed by traffic from HN.

Custom events

"How many signups happened this month?"

Calls events.list with name="signup" and period="30d".

"Break down signups by plan"

Calls events.list with name="signup" and group_by="plan". Returns counts per property value.

Funnels (Pro)

"Create a funnel from pricing page to signup to purchase"

Calls funnels.create with steps ["pageview:/pricing", "signup", "purchase"]. Returns step-by-step conversion rates immediately.

"Compare funnel conversion for US vs Germany"

Two calls to funnels.list, one with country="US" and one with country="DE".

Alerts (Pro)

"Alert me if visitors drop by 30% week over week"

Calls alerts.create with metric="visitors", condition="drops_by", threshold=30, period="7d".

Workflows

"Why did traffic drop last week?"

Follows the traffic_diagnosis prompt. Systematically checks channels, countries, devices, and pages to isolate the root cause.

"Audit our conversion funnel"

Follows the conversion_audit prompt. Analyzes funnel drop-offs, segments by device/country/channel, and identifies the biggest optimization opportunity.

Environment variables

FAQ

Do I need an API key for the Remote MCP install? No. Installing from the Clamp dashboard handles auth automatically. The API key is only needed for stdio (this npm package), self-hosted instances, CI, and custom clients.

How is this different from the Clamp dashboard? Same data, different access pattern. Use the dashboard when you want a chart; use the MCP when you want the agent to do the digging — diagnose a drop, compose a funnel, run a weekly report — and return the answer in chat.

Can I self-host? Yes. Point CLAMP_API_URL at your self-hosted Clamp instance, or run the stdio server inline in your own infrastructure. The MCP tools work against any Clamp API endpoint that speaks the same protocol.

Does this work for read-only audits, or can the agent make changes? Both. The Free-tier tools are all read-only except for cohorts.create / cohorts.delete; the Pro tools (funnels.create, funnels.delete, alerts.create, alerts.delete) also write. Scope the connection from the dashboard if you only want read access.

Will the agent know about my custom events? Yes. events.observed_schema returns the actual fired-event signatures with per-property type observations, so the agent can answer "what's in my event schema" without you pasting anything.

License

MIT