Skip to main content

MCP Server for AI Assistants

The Sealmetrics MCP Server lets AI assistants like Claude (Claude Code, Claude Desktop, Claude.ai), ChatGPT, Cursor, Codex, Windsurf, VS Code, and other MCP clients query your Sealmetrics analytics — traffic, conversions, campaigns, and more — in plain natural language.

There are two ways to connect, and you only need one:

Remote MCP (hosted)Local MCP (npx)
SetupPaste one URL — no installAdd an npx command with your API key
Runs onSealmetrics serversYour machine
AuthHandled by the endpoint — nothing to pasteSEALMETRICS_API_KEY in the config
Node.js requiredNoYes (v18+)
Read analytics42 tools52 tools
Write channel rules (drafts)NoYes, with the right API key
Register a site / install the tracker from chatNoYes
Best forCodex, Cursor, Claude, ChatGPT and any client that supports remote MCPEditing channel rules with an assistant, installing the tracker, offline setups, or pinning a version

We recommend the remote MCP for most people — it takes about two minutes per client and there's nothing to install or keep updated. Jump to the remote setup ↓

The hosted endpoint is read-only by design

The remote server registers no write tools at all. That is a property of the connection, not of your API key: a key that can edit channel rules still writes nothing over the hosted endpoint, because the tools are not there to call. If you want an assistant to draft channel rules, use the local server — and even there, it can only ever create drafts. See What each connection can do.

Don't have an account yet?

Both options assume you already have a Sealmetrics account and API key. If you want your AI assistant to create the account for you from the chat (no key, no terminal), use the one-click AI Agentic Package (Claude & Codex) instead.

What is MCP?​

The Model Context Protocol (MCP) is an open standard that allows AI assistants to securely connect to external data sources. The Sealmetrics MCP server exposes your analytics — traffic, conversions, campaigns, and more — as tools your assistant can call in plain language, with no SQL and no dashboard. You can run it two ways: as the hosted remote server (Sealmetrics runs it; you just point your client at a URL) or as the local server (it runs on your machine via npx).

What can you ask Claude?​

Once connected, you can ask questions like:

  • "Show me an overview of my site for the last 7 days"
  • "What are the top traffic sources this month?"
  • "Compare this month's conversions with last month"
  • "Which landing pages have the highest bounce rate?"
  • "Show me revenue by country for the last quarter"
  • "What devices do my visitors use?"
  • "Analyze my top 3 campaigns and tell me which has the best conversion rate"

The hosted remote server is the fastest way to connect. There's nothing to install and nothing to keep updated — you point your AI client at a single URL and start asking questions. It works with Claude, ChatGPT, Cursor, Codex, VS Code, and any client that supports remote (Streamable HTTP) MCP.

Endpoint:

https://mcp.sealmetrics.com/mcp

Add that URL in your client and the Sealmetrics tools become available — no local install and no key to paste. If your client shows an authorization or Connect step when you add the server, follow its prompts to finish linking.

Fewer tools, lower token use

Append ?discovery=progressive to the endpoint (https://mcp.sealmetrics.com/mcp?discovery=progressive) to load tool definitions on demand instead of all at once. Every tool stays callable; your assistant just discovers them as needed, which lowers token usage on clients with tight context limits.

Claude Code​

Add the remote server with the HTTP transport (run inside your project, or add -s user to make it available in every project):

claude mcp add --transport http sealmetrics https://mcp.sealmetrics.com/mcp

Run /mcp inside Claude Code to check the connection. If it shows an authorization step, follow the prompt to finish linking.

Claude.ai & Claude Desktop​

  1. Open Settings → Connectors.
  2. Click Add custom connector.
  3. Name it Sealmetrics and paste the URL: https://mcp.sealmetrics.com/mcp
  4. Click Add (then Connect if prompted).

The Sealmetrics tools now appear in the connectors menu of any chat.

ChatGPT​

Remote MCP connectors are available on ChatGPT plans that support connectors (and via developer mode).

  1. Open Settings → Connectors (or Settings → Connectors → Advanced → Developer mode).
  2. Click Create / Add custom connector.
  3. Name it Sealmetrics and set the MCP Server URL to https://mcp.sealmetrics.com/mcp.
  4. Save (and complete any Connect step the dialog shows).

Once connected, enable the Sealmetrics connector in the composer's tools/connectors menu before asking about your data.

Cursor​

Add this to your MCP config (~/.cursor/mcp.json for all projects, or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "sealmetrics": {
      "url": "https://mcp.sealmetrics.com/mcp"
    }
  }
}

Reload Cursor and open Settings → MCP to confirm Sealmetrics is listed (click Connect if it prompts you).

Codex (OpenAI)​

Add this to ~/.codex/config.toml:

[mcp_servers.sealmetrics]
url = "https://mcp.sealmetrics.com/mcp"

Restart Codex — the Sealmetrics tools become available on the next session.

VS Code (Copilot) & other MCP clients​

Any client that supports remote MCP uses the same URL. In VS Code, add a .vscode/mcp.json:

{
  "servers": {
    "sealmetrics": {
      "type": "http",
      "url": "https://mcp.sealmetrics.com/mcp"
    }
  }
}
Client only supports local (stdio) servers?

A few older clients can't connect to a remote URL directly. Bridge to it with mcp-remote:

{
  "mcpServers": {
    "sealmetrics": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.sealmetrics.com/mcp"]
    }
  }
}

Verify it works​

Open your assistant and ask:

"List my Sealmetrics sites"

It should respond with your sites. If it does, you're all set — skip ahead to Available tools.

Local MCP server (npx)​

Prefer to run the server on your own machine — for offline setups, or to pin a specific version? The local server runs via npx and authenticates with your API key. The steps below cover it end to end.

Step 1: Verify Node.js is installed​

Open your terminal and run:

node --version

You need v18 or higher. If you don't have it, download it from nodejs.org.

Step 2: Get your API Key​

  1. Log in to your Sealmetrics dashboard at my.sealmetrics.com
  2. Go to Settings > API Keys (direct link)
  3. Click Create API Key
  4. Give it a name (e.g. "Claude MCP") and click Create
  5. Copy the key — it starts with sm_ (e.g. sm_AbCdEf123...)
Important

The full API key is only shown once. Copy it immediately and store it in a safe place. A key's permissions cannot be edited afterwards — to change them, revoke the key and create a new one.

Want the assistant to draft channel rules?

Leave Read access checked and also check Channel Rules: Drafts (channel_rules:write). That enables the four write tools on the local server, which can only ever create drafts. Do not check Channel Rules: Publish unless you want scripts to change live classification without review. Full walkthrough: Channel Grouping → Using the MCP.

Step 3: Find your Site ID​

  1. Go to Settings > Sites (direct link)
  2. Click on the site you want to query
  3. The Site ID is displayed at the top of the site settings page (e.g. my-store)
tip

If you only have one site, you can skip this step — just ask Claude to "list my sites" and it will find it for you.

Step 4: Configure your Claude client​

Choose the client you use:

Claude Code​

Add the server with a single command (run inside your project):

claude mcp add sealmetrics \
  -e SEALMETRICS_API_KEY=sm_your_key_here \
  -e SEALMETRICS_SITE_ID=your-site-id \
  -- npx -y @sealmetrics/mcp

Replace sm_your_key_here with your API key from Step 2, and your-site-id with your Site ID from Step 3.

Global configuration

By default the server is added for the current project. Add -s user to make Sealmetrics available in all your projects.

Claude Desktop​

  1. Open Claude Desktop
  2. Go to Settings (gear icon) > Developer > Edit Config
  3. Add the following configuration:
{
  "mcpServers": {
    "sealmetrics": {
      "command": "npx",
      "args": ["-y", "@sealmetrics/mcp"],
      "env": {
        "SEALMETRICS_API_KEY": "sm_your_key_here",
        "SEALMETRICS_SITE_ID": "your-site-id"
      }
    }
  }
}
  1. Save and restart Claude Desktop completely (Cmd+Q on macOS, then reopen)
One-click alternative

You can skip the JSON entirely with the Sealmetrics Claude Desktop extension — download, double-click, paste your key. The same extension can also create an account for you if you don't have one yet.

Codex (OpenAI)​

Add this to ~/.codex/config.toml:

[mcp_servers.sealmetrics]
command = "npx"
args = ["-y", "@sealmetrics/mcp"]
env = { SEALMETRICS_API_KEY = "sm_your_key_here", SEALMETRICS_SITE_ID = "your-site-id" }

Restart Codex after saving.

Cursor, Windsurf, VS Code & other MCP clients​

Any MCP-compatible client uses the same server. Add this block to your client's MCP config (in Cursor, ~/.cursor/mcp.json):

{
  "mcpServers": {
    "sealmetrics": {
      "command": "npx",
      "args": ["-y", "@sealmetrics/mcp"],
      "env": {
        "SEALMETRICS_API_KEY": "sm_your_key_here",
        "SEALMETRICS_SITE_ID": "your-site-id"
      }
    }
  }
}

Step 5: Verify it works​

Open Claude and ask:

"List my Sealmetrics sites"

Claude should respond with a list of your sites. If it does, you're all set!

Configuration reference​

VariableRequiredDescription
SEALMETRICS_API_KEYYesYour API key from Settings > API Keys. Starts with sm_.
SEALMETRICS_SITE_IDNoDefault Site ID from Settings > Sites. If set, you don't need to specify the site in every query.
SEALMETRICS_BASE_URLNoAPI base URL. Default: https://my.sealmetrics.com/api/v1. Only change this for custom deployments.

Available tools​

Claude uses these tools automatically when you ask questions — you never need to call them directly. The 52 read-only analytics tools are grouped below by category.

What each connection can do​

The two connections do not expose the same tools. A tool missing from the hosted endpoint is missing because it was never registered there — no API key, scope or setting brings it back on that connection.

Hosted endpoint (https://mcp.sealmetrics.com/mcp)Local server (npx -y @sealmetrics/mcp)
Read-only analytics tools42 of the 52 belowAll 52
search / fetch (ChatGPT compatibility)YesNo
Channel-rule write tools (draft-only)NoYes — 4 tools
Setup tools (register a site, install and verify the tracker)NoYes — 8 tools
Picking the siteFrom the connection; injected automatically when it covers a single siteSEALMETRICS_SITE_ID, or name the site per question

The 10 read-only tools the hosted endpoint omits are Segments (list_segments, get_segment), Alerts (list_alerts, get_alert_history, get_alert_stats), Bot detection (get_bot_stats, get_suspicious_sessions) and Webhooks (list_webhooks, list_webhook_deliveries, get_webhook_stats). Their endpoints require a dashboard session, which a hosted connection never has. Everything else — including the channel-rule reads get_channels, list_channel_rules and test_channel_rules — works on both.

Sites​

ToolDescription
list_sitesList all sites (web properties) accessible with your API key, with IDs, names, and domains
get_siteGet detailed info about a specific site: name, domains, timezone, configuration, and tracking status

Overview​

ToolDescription
get_overviewDashboard KPIs: pageviews, entrances, bounce rate, conversions, revenue, with time series and optional period comparison

Traffic, sources & campaigns​

ToolDescription
get_traffic_sourcesTraffic by source (utm_source): google, facebook, direct, etc.
get_traffic_mediumsTraffic by medium (utm_medium): organic, cpc, email, referral, social, etc.
get_campaignsPerformance by campaign (utm_campaign) with entrances, conversions, and revenue
get_termsTraffic by UTM term (keyword) with source/medium/campaign/country filters
get_top_sourcesTop traffic sources ranked by entrances (compact, non-paginated)
get_top_campaignsTop campaigns ranked by entrances (compact, non-paginated)
get_top_termsTop UTM terms (keywords) ranked by entrances (compact, non-paginated)
get_top_referrersTop referrer domains ranked by entrances

Pages & content​

ToolDescription
get_pagesMetrics per page URL path: pageviews and entrances, with multi-value filters and include dimensions
get_landing_pagesLanding page performance: entrances, bounce rate, conversions
get_top_pagesTop pages ranked by page views (compact, non-paginated)
get_top_landing_pagesTop landing pages ranked by entrances (compact, non-paginated)
get_landing_pages_by_content_groupLanding page metrics grouped by content grouping
get_content_groupsMetrics grouped by content group (content_grouping)

Conversions​

ToolDescription
get_conversionsConversions by type (purchase, signup) with count, revenue, and average order value
get_microconversionsMicroconversions (add_to_cart, newsletter_signup, etc.) by type with counts
list_microconversion_typesList available microconversion type names for a site
get_microconversion_detailsDetailed breakdown of a microconversion type by source, medium, campaign, country, device, browser, OS

Raw events (event-level)​

ToolDescription
get_conversions_rawRaw conversion rows (one per event) with timestamp_utc/timestamp_local; date range capped at 31 days
get_microconversions_rawRaw microconversion rows (one per event); date range capped at 31 days
get_conversion_items_rawOne row per item inside a conversion (per-product); always includes item properties (sku, price, quantity)

Audience (geo, devices, browsers, OS)​

ToolDescription
get_countriesTraffic by country (ISO 3166-1 alpha-2) with entrances, conversions, and revenue
get_devicesDevice type, browser, and OS breakdown in a single call
get_device_typesTraffic by device type (desktop, mobile, tablet), paginated
get_browsersTraffic by browser (Chrome, Safari, Firefox, Edge...), paginated
get_operating_systemsTraffic by operating system (Windows, macOS, iOS, Android, Linux...), paginated

Channels​

ToolDescription
get_channelsTraffic grouped by channel: Paid Search, Organic, Social, Direct, Email, Referral, etc.
get_top_channelsTop channels ranked by entrances (compact, non-paginated)
list_channel_rulesList channel group rules that classify traffic into channels
test_channel_rulesTest how a source/medium/campaign combination would be classified
create_channel_ruleLocal only. Create a new channel rule as a draft (never live)
update_channel_ruleLocal only. Update a channel rule — drafts only
delete_channel_ruleLocal only. Delete a channel rule — drafts only
import_channel_rulesLocal only. Bulk-import rules as drafts; defaults to dry_run=true

The four write tools exist only on the local server and need an API key with the channel_rules:write scope. They follow a strict draft-only invariant: the MCP can never touch a live rule or activate anything, whatever scope the key carries. Publishing is always a human action from the dashboard. See Channel Grouping for the full workflow and the key setup.

Custom properties (custom dimensions)​

ToolDescription
list_property_keysList available custom property keys from conversions and/or microconversions
get_property_valuesProperty values with counts, grouped by a UTM parameter (paginated)
get_property_breakdownComplete property breakdown (pivot-table style) with counts and revenue

Funnel​

ToolDescription
get_funnelFunnel analysis with step-by-step conversion rates and dropoff

Bot detection​

ToolDescription
get_bot_statsBot detection overview: score distribution, top flags, human vs suspected-bot daily trend
get_suspicious_sessionsSessions with high bot-suspicion scores, with detected flags

Segments​

ToolDescription
list_segmentsList all segments (saved filter sets) available for a site
get_segmentGet details of a specific segment, including its filter definition

Alerts​

ToolDescription
list_alertsList alert rules: name, metric, condition, threshold, and status
get_alert_historyHistory of triggered alerts: when they fired, status, and triggering rule
get_alert_statsAlert statistics: total rules, active alerts, resolved count, acknowledgement rate

Webhooks​

ToolDescription
list_webhooksList webhook endpoints: URL, subscribed event types, and active status
list_webhook_deliveriesDelivery attempts for an endpoint: HTTP status, response time, success/failure
get_webhook_statsDelivery statistics for an endpoint: total, success rate, avg response time, failures

Tracking code​

ToolDescription
get_tracking_codeTracking pixel <script> tag plus the full JS API reference and implementation examples

Common parameters​

ParameterValuesDefaultDescription
site_idstring$SEALMETRICS_SITE_IDSite to query
periodtoday, yesterday, 7d, 30d, 90d, this_month, last_month, this_year, etc.30dTime period
compareprevious, yoynoneCompare with previous period or year-over-year
limit1-10020Max rows returned
pagenumber1Page number for paginated results
sort_byvaries per toolvariesSort field
sort_orderasc, descdescSort direction
countryISO-3166-1 alpha-2 code (ES, US) or UnknownnoneCountry filter. Not the country name — see below
landing_pagepath (/shoes/)noneEntry-page filter. Only get_top_sources and the three raw tools accept it

Filters: country and landing_page​

Tools reject arguments they don't support. If a tool gets an argument it does not declare, it returns an error listing the arguments it does accept, and it never queries the API:

Unknown argument "landing_page" for get_top_channels. Accepted: site_id, period, ...

Before version 1.10.0, those arguments were dropped without warning. An assistant could pass country to a tool that had no such filter, get site-wide numbers back and present them as filtered.

country takes a code, never a name. Use an ISO-3166-1 alpha-2 code (ES, US, DE; case does not matter) or the literal Unknown. A country name is rejected:

Invalid country "Spain": country must be an ISO-3166-1 alpha-2 code (e.g. ES for Spain) or 'Unknown'; call get_countries to see the codes with traffic.

The server deliberately does not translate names into codes: the assistant corrects itself from the error. The check is on format, so a two-letter code with no traffic returns empty results, not an error. get_countries lists the codes that have traffic for a site and period. Unknown is traffic whose browser timezone maps to no country (the country is always derived from the timezone, never from the IP — see country detection). country: "Unknown" isolates that traffic, and picking the real codes excludes it.

Tools that accept country: most reports, including get_overview, get_microconversions, get_campaigns, get_devices, get_traffic_mediums and get_traffic_sources. Those six gained it in 1.10.0. Each tool's schema lists exactly what it accepts.

landing_page is accepted by get_top_sources and by get_conversions_raw, get_microconversions_raw and get_conversion_items_raw (on the raw tools, one path or a list). The match is exact and case-insensitive, and the trailing slash counts (/shoes and /shoes/ are different pages). Copy the path from get_top_landing_pages.

With landing_page, get_top_sources answers "which sources brought the sessions that entered on this page", so its totals add up to that page's entrances. It reads the landing-page report, which has no pageview data, so those rows have no page_views field. Every other metric is present. Without landing_page, the tool responds as before and the rows include page_views.

All period values​

These are the only accepted period values (the full set is validated by the server):

PeriodDescription
todayToday
yesterdayYesterday
7d, 30d, 90dLast 7 / 30 / 90 days
12mLast 12 months
this_week, this_month, this_quarter, this_yearCurrent period
wtd, mtd, qtd, ytdPeriod to date (week / month / quarter / year)
last_week, last_month, last_quarter, last_yearPrevious period

Troubleshooting​

Remote MCP: the client doesn't show the Sealmetrics tools​

Double-check the URL is exactly https://mcp.sealmetrics.com/mcp, then reload the client (or restart it). If the client shows a Connect or authorization step next to Sealmetrics, complete it. In Claude Code, run /mcp to re-check the connection.

Remote MCP: connected, but "access denied" to a site​

Ask "list my sites" to confirm which sites are available, then query one of those. If a site you expect is missing, check its permissions in Settings > Sites.

Remote MCP: client won't accept a URL​

Some older clients only support local (stdio) servers. Bridge to the remote endpoint with mcp-remote — see the note above.

Local MCP: "404 Not Found" or "@sealmetrics/mcp-server is not in this registry"​

Your configuration points at the old package name. @sealmetrics/mcp-server was renamed to @sealmetrics/mcp in v1.3.0 (June 2026) and removed from the npm registry, so npx can no longer download it.

Edit your config and replace the package name:

"args": ["-y", "@sealmetrics/mcp@latest"]

Leave your API key and site ID unchanged. Save, restart your client completely, and ask "list my sites". If the error persists, npx may have cached the broken resolution — run rm -rf ~/.npm/_npx and restart again.

Local MCP: Claude doesn't see the Sealmetrics tools​

  1. Claude Code: Make sure .mcp.json is in your project root and restart Claude Code
  2. Claude Desktop: Save the config file and restart the app completely (Cmd+Q on macOS)
  3. Verify Node.js 18+ is installed: node --version

"Invalid API key"​

Your API key is incorrect or expired. Go to Settings > API Keys and generate a new one.

"site_id is required"​

Either set SEALMETRICS_SITE_ID in your config, or ask Claude to "list my sites" first, then specify the site in your question.

"Access denied to site X"​

Your API key doesn't have permission for that site. Check your token permissions in Settings > API Keys.

A country filter is rejected, or changes nothing​

country takes an ISO code (ES), not a name (Spain). Ask the assistant to call get_countries first and filter using the codes it returns. If the error is Unknown argument "country", that tool has no country filter, so ask the question with a tool that does. On a local server older than 1.10.0, both mistakes returned unfiltered numbers without any error, so update to the latest version. See Filters.

"npx: command not found"​

Install Node.js from nodejs.org. npx is bundled with Node.js.

Test the server manually​

You can verify the server starts correctly from your terminal:

SEALMETRICS_API_KEY="sm_your_key_here" npx -y @sealmetrics/mcp

If it starts without errors, the server is working. Press Ctrl+C to stop it.

How it works​

Remote server: Sealmetrics hosts the MCP server at https://mcp.sealmetrics.com/mcp. Your client connects to it over HTTPS (Streamable HTTP) and the Sealmetrics tools become available — nothing runs on your machine and there's nothing to install or update.

Local server: the MCP server runs on your machine via npx and communicates with the Sealmetrics API over HTTPS. No analytics data is stored locally.

Your machine                             Sealmetrics cloud
┌──────────────────────────┐            ┌──────────────────────┐
│                          │            │                      │
│  Claude Code / Desktop   │            │  my.sealmetrics.com  │
│          |               │            │                      │
│  @sealmetrics/mcp  │─ HTTPS ─>│  /api/v1/*          │
│  (runs locally via npx)  │<── JSON ───│                      │
│          |               │            │                      │
│  Claude reads the data   │            └──────────────────────┘
│  and answers your query  │
│                          │
└──────────────────────────┘
  • Authenticated via X-API-Key header (your key never leaves your machine)
  • Automatic retries with exponential backoff on rate limits
  • 30-second timeout per request
  • No data stored locally

Resources​

Need help?​

Written and maintained by the Sealmetrics Team