@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.get	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.get with name="pricing-to-signup" and device_type="mobile".

"Compare funnel conversion for US vs Germany"

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

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

Calls funnels.get 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.