Clamp Sh MCP README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Clamp Sh MCP listing page.
@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.
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:
Claude Code
Claude Desktop and Cursor
Both clients use the same shape — drop this into claude_desktop_config.json or .cursor/mcp.json:
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 | Any core metric over time with automatic granularity (visitors, sessions, bounce rate, avg duration, or event counts). |
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, country, city, region, device_type, browser, browser_version, os, os_version, entry_page, exit_page, channel, or any UTM field. |
pages.engagement | Per-page metrics with view: summary, engagement (adds 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. |
events.observed_schema | The actual fired-event signature with per-property type observations. Diff against a local event-schema.yaml to surface schema drift. |
events.property_values | Top distinct string-typed values a property has taken on a specific event. Use to discover the value space before defining a cohort filter or running events.list with property=. |
revenue.sum | Sum Money-typed event properties. Split by currency, group by any dimension, switch to first-touch via attribution_model. Drill-in filters: plan, product, first_touch_dim + first_touch_value. |
revenue.summary | The whole Revenue tab in one call: revenue per currency, customers, orders, AOV, LTV, MRR (running balance) + ARR, per-plan rollup (where mrr_contribution is the cumulative MRR balance per plan, not the in-period delta), per-product rollup, prior-period comparison, and mode flags (is_subscription, has_one_time) so callers can render conditionally. |
revenue.retention | Cohort revenue retention on MRR-on-MRR math. Per window: mature_size, retained, retention_rate, mrr_at_d, baseline_mrr_mature, nrr (net revenue retention; >1.0 = net expansion). Anchored at the customer's first subscription_started. |
revenue.timeseries | Plot one revenue metric per bucket. metric accepts revenue (Money sum), mrr (running balance, picks up from prior period), customers (distinct paying), or transactions (event count). |
sessions.paths | Aggregate session paths: top entry → exit pairs with pages per session and duration. |
users.journey | Chronological session-and-event reconstruction for one anonymous ID. |
cohorts.create / cohorts.list / cohorts.retention / cohorts.compare / cohorts.delete | Define cohorts by event + period + filter; query retention curves; compare 2–10 cohorts side-by-side on the same retention windows; delete a saved cohort by name (definitions are immutable, so delete + re-create is the rename/restructure flow). |
errors.list / errors.groups / errors.timeline / errors.context | Recent errors, fingerprint-grouped errors with affected-user counts, error rate over time, and breadcrumbs leading to a single error. |
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. Steps accept property predicates: cta_click[location=hero][plan=pro]. Names must be unique within a project — a duplicate-name call returns 409. |
funnels.list | List funnels or fetch one with cohort filters (country, channel, device, UTM). |
funnels.delete | Delete a saved funnel by name (definitions are immutable, so delete + re-create is the rename/restructure flow). |
alerts.create | Set up metric alerts (e.g. "visitors drops_by 30% over 7d"). |
alerts.list / alerts.delete | List and remove alerts. |
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.
| 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.
"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
| 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. |
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