@clamp-sh/mcp

Stdio MCP server for Clamp analytics. Gives your AI assistant read access to pageviews, visitors, referrers, countries, cities, devices, custom events, and conversion funnels. Pro plans can create funnels and set up metric alerts.

Works with any MCP client: Claude Desktop, VS Code Copilot, Cursor, Windsurf, Cline, or anything that speaks the Model Context Protocol.

Using Cursor, VS Code, Claude Code, or Claude Desktop? There is a one-click remote install in the Clamp dashboard that handles auth via OAuth, no API key to paste. Open a project, go to the Installation tab, and pick your editor. This package is the stdio path for CI, headless agents, custom clients, and self-hosted Clamp instances.

Setup

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

Then set your API key:

export CLAMP_API_KEY="sk_proj..."

Claude Desktop

Add to claude_desktop_config.json:

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

Cursor

Add to .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)

| Tool | What it does | |---|---| | traffic.overview | Pageviews, visitors, sessions, bounce rate, avg duration. Period comparison included. | | traffic.timeseries | Event counts over time with automatic granularity. | | traffic.compare | Compare any metric across two arbitrary periods. Returns absolute and percent delta. | | traffic.live | Visitors active in the last N minutes plus their top pages, referrers, and countries. | | breakdown | Group visitors and pageviews by any dimension: pathname, referrer_host (channel comes back joined), country, city (country joined), device_type, browser, browser_version, os, os_version, entry_page, exit_page, region, channel, or any UTM field. | | pages.engagement | Per-page metrics with view: summary (pageviews+visitors), engagement (adds avg engagement seconds and bounce rate), sections (per-section view counts for one pathname; needs the section-views SDK extension). | | events.list | Custom event counts with property filtering and grouping. | | revenue.sum | Sum revenue from Money-typed event properties. Split by currency, optionally grouped by referrer_host, country, channel, UTM, etc. | | sessions.paths | Aggregate session paths: top entry → exit pairs with pages per session and duration. | | projects.list | List all projects this credential can access. | | docs.search | Keyword-search the Clamp docs index. |

Pro

| Tool | What it does | |---|---| | funnels.create | Define and immediately evaluate a multi-step conversion funnel. | | funnels.list | Retrieve a funnel with cohort filters (country, channel, device, UTM). | | alerts.create | Set up metric alerts (e.g. "visitors drops_by 30% over 7d"). | | alerts.list | List every alert configured for the project. | | alerts.delete | Delete an alert by id. |

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, device_type, and the full UTM set (utm_source, utm_medium, utm_campaign, utm_content, utm_term). Funnels accept the same cohort filters.

referrer_host — Filter results to visitors from a specific source. Must match the value returned by breakdown(dimension="referrer_host") exactly (e.g. "news.ycombinator.com", "twitter.com", "github.com"). Works on overview, breakdown, pages.engagement, events, timeseries, and funnels.

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

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

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.

| Prompt | What it produces | |---|---| | weekly_report | Traffic summary, top pages, referrers, countries, one actionable insight. | | traffic_diagnosis | Root-cause analysis for traffic changes. Drills into channels, countries, devices, pages. | | conversion_audit | Funnel drop-off analysis with cohort segmentation. | | channel_breakdown | Traffic quality comparison across sources (volume vs engagement). | | page_performance | Deep-dive on a single page: trends, referrers, devices, engagement vs site average. |

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.

"What's the bounce rate on /pricing?"

Calls traffic.overview with pathname="/pricing". Returns metrics for that single page, including comparison to the prior period.

"Show me traffic trends for the last 90 days"

Calls traffic.timeseries with period="90d". 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.

"Show me only organic search traffic to /blog"

Calls breakdown with dimension="referrer_host", channel="organic_search", and pathname="/blog".

"Which countries send the most traffic?"

Calls breakdown with dimension="country". Returns ISO country codes with visitor and pageview counts.

"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.

"Which pages did Hacker News visitors read?"

Calls pages.engagement with referrer_host="news.ycombinator.com" (default view="summary"). Returns only pages viewed by traffic from HN.

"How's traffic from Twitter trending?"

Calls traffic.timeseries with referrer_host="twitter.com". Returns the pageview curve for visitors from a single source.

Devices

"What's the mobile vs desktop split?"

Calls breakdown with dimension="device_type".

"Which browsers are my visitors using?"

Calls breakdown with dimension="browser".

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 (e.g. free: 42, pro: 18, growth: 7).

"How many signups came from the spring campaign?"

Calls events.list with name="signup" and utm_campaign="spring-launch".

Funnels (Pro)

Funnels let you track multi-step conversion and filter by cohorts: country, channel, device type, and UTM parameters. This is where you answer questions like "how many mobile users from Germany actually signed up?"

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

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

"How does the pricing-to-signup funnel convert on mobile?"

Calls funnels.list with name="pricing-to-signup" and device_type="mobile".

"Compare funnel conversion for US vs Germany"

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

"What's the funnel conversion for visitors from Google?"

Calls funnels.list with channel="organic_search".

"How many mobile users from Germany signed up?"

Create a single-step funnel with steps=["signup"] and filter with country="DE" and device_type="mobile". Cohort filtering works on any funnel, including single-event funnels.

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".

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

Calls alerts.create with metric="bounce_rate", condition="above", threshold=70, pathname="/pricing".

Workflows

"Run a weekly report"

Follows the weekly_report prompt. Calls overview, top pages, referrers, countries, and timeseries, then synthesizes a structured report with trends and one actionable insight.

"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.

"How is /pricing performing?"

Follows the page_performance prompt. Pulls page-specific metrics, referrers, device split, and compares engagement to the site average.

Environment variables

| Variable | Required | Description | |---|---|---| | CLAMP_API_KEY | Yes | Project API key (sk_proj...). | | CLAMP_API_URL | No | Override the API base. Defaults to https://api.clamp.sh. Set this when pointing at a self-hosted Clamp instance. |