@clarvivo/mcp

Install Clarvivo analytics without leaving your coding agent. The server detects the app framework, reuses or creates the right Clarvivo project, and returns the exact file and code edit. It can then verify real traffic, connect payment revenue, and configure events, funnels, and alerts.

The 60-second flow

1. Sign in to Clarvivo. New users create an API token right on the dashboard page after signing in; paying users create one in Settings → API tokens.

2. Add this MCP server to your coding client with CLARVIVO_API_TOKEN in its environment.

3. Ask the agent: “Set up Clarvivo analytics for example.com.”

4. The agent detects the framework, calls setup_analytics, makes the returned edit, and deploys through your normal workflow.

5. Visit the deployed site, then ask the agent to verify the installation.

The tracker observes history.pushState, history.replaceState, and popstate, so client-side SPA route changes work automatically. Do not add router hooks.

Related MCP server: ai-google-analytics-mcp

Tools

setup_analytics supports Next.js App Router, Next.js Pages Router, Vite (React/Vue/Svelte), Create React App, Astro, SvelteKit, Nuxt, Remix / React Router v7, Gatsby, Docusaurus, and static HTML.

Revenue by source

get_revenue_sources is the tool that answers "which campaigns made money". It splits recorded revenue two ways: by marketing source (utm_source) and, separately, by payment provider — those are different questions and conflating them is the usual mistake.

Revenue whose payment carried no Clarvivo campaign context is grouped as Direct. That means unattributed, not "the visitor typed the URL in". verify_revenue reports what share of revenue is attributed at all; if that share is low, treat the split as a floor rather than a verdict.

Search Console

get_search_queries and get_search_pages proxy Google's Search Analytics API, so each call spends the project's Search Console quota; both cap what they return and report the total they trimmed. get_search_trends reads Clarvivo's stored snapshots instead, costs no quota, and is the one to reach for on repeated checks.

All three need a token carrying search:read, and the project must already have Search Console connected in Clarvivo — the MCP reads the data, it does not run the Google sign-in for you.

Read your data

Ask for a quick overview with get_stats, then use get_traffic_sources, get_pages, or get_audience when you need a focused breakdown. These tools aggregate the full reporting window inside the MCP server, cap every returned list, and never place raw daily analytics rows into the model context. Their default window is 30 days and accepts 1–90 days.

Analytics reads require the analytics:read token scope. If the account is still awaiting its first payment or its access has lapsed, the tools stop at the same billing wall as the dashboard and link to the billing page.

get_stats also reports revenue when the token carries revenue:read. Without that scope it still returns the full traffic summary and says why the revenue block is missing, rather than failing the whole call for an optional extra.

Grant every scope you intend to use when you create the token. A token's scopes are fixed at creation — they cannot be edited afterwards, only revoked and replaced — so a missing scope means minting a new token, updating CLARVIVO_API_TOKEN, and restarting the MCP client. The tools span projects:read, projects:write, analytics:read, revenue:read, revenue:write, funnels:read, funnels:write, events:write, alerts:write and search:read.

Export

export_data writes the result to disk instead of returning file contents. CSV and JSON use Clarvivo's paid export routes; pdf creates a slim, self-contained .html report with headline metrics, channels, top pages, and sources. Open that file in a browser and use Print → Save as PDF, matching the dashboard workflow.

The default filename is clarvivo-export-<project>-<date>.<ext> in the current working directory. A custom path must remain inside that directory and cannot contain ... Existing files are protected unless overwrite: true is passed. Data export remains plan-gated and uses the existing analytics:read scope.

Connect payments

1. Ask the agent: “Connect Clarvivo revenue for this project.”

2. connect_revenue detects the payment SDK from package.json, connects the provider, and returns the webhook URL plus the exact events to enable.

3. Copy the provider signing secret from its webhook settings into Clarvivo at Dashboard → Settings → Integrations. Do not paste the secret into the agent or tool call.

4. Apply the returned client-to-server attribution edit. It reads clv_vid from browser local storage and puts it in the provider's supported metadata, custom data, or notes field. This is the step that makes revenue-by-channel work.

5. Complete a test payment, wait for delivery, then ask: “Verify Clarvivo revenue.”

The checkout snippet adapts to a Next.js route handler, Express handler, or serverless function. If no supported SDK is found, the tool returns a server-only signed POST /api/ingest/:apiKey/revenue example using CLARVIVO_INGEST_SECRET; that secret must never enter browser code.

Track events & funnels

1. Ask: “Track successful signups in Clarvivo.” add_event registers the event and proposes a window.clarvivo.trackEvent(...) call for the success handler. The tool reports the edit; your coding agent applies it.

2. Ask: “Create a Signup funnel with Landing, Pricing, and Success.” create_funnel orders the steps, reuses an existing same-name funnel on retries, and points out steps that do not yet match a tracked page.

3. Ask: “Alert me when conversion drops by 20%.” create_alert reuses an existing alert of that type instead of creating duplicates.

The browser SDK global is window.clarvivo. It exposes trackEvent(name, properties), trackConversion(value, currency), and trackPurchase(...).

Configuration

Replace clv_live_REPLACE_ME below. Tokens are secrets; keep personal config files out of source control. The tracking API key returned by tools is intentionally public because it ships in page source.

For local development or self-hosting, add CLARVIVO_BASE_URL (for example http://127.0.0.1:5000) beside the token.

Claude Code

The official CLI accepts --env before the -- separator. This user-scoped command works from every project:

claude mcp add clarvivo --scope user \
  --env CLARVIVO_API_TOKEN=clv_live_REPLACE_ME \
  -- npx -y @clarvivo/mcp

Check it with claude mcp get clarvivo. See Claude Code MCP documentation.

Cursor

Create .cursor/mcp.json in a project, or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "clarvivo": {
      "command": "npx",
      "args": ["-y", "@clarvivo/mcp"],
      "env": {
        "CLARVIVO_API_TOKEN": "clv_live_REPLACE_ME"
      }
    }
  }
}

One-click install with a placeholder token (review and replace it in Cursor before starting the server):

Add Clarvivo to Cursor

Cursor requires the single-server config to be JSON-stringified and base64-encoded in the config parameter. See Cursor MCP configuration and Cursor install links.

Codex CLI

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

[mcp_servers.clarvivo]
command = "npx"
args = ["-y", "@clarvivo/mcp"]

[mcp_servers.clarvivo.env]
CLARVIVO_API_TOKEN = "clv_live_REPLACE_ME"

The equivalent command is:

codex mcp add clarvivo \
  --env CLARVIVO_API_TOKEN=clv_live_REPLACE_ME \
  -- npx -y @clarvivo/mcp

This was checked against the installed codex mcp add --help and the official OpenAI Codex MCP documentation.

Windsurf

Open ~/.codeium/windsurf/mcp_config.json and add:

{
  "mcpServers": {
    "clarvivo": {
      "command": "npx",
      "args": ["-y", "@clarvivo/mcp"],
      "env": {
        "CLARVIVO_API_TOKEN": "clv_live_REPLACE_ME"
      }
    }
  }
}

Refresh the MCP list after saving. See Windsurf’s MCP documentation.

Cline

Open Cline’s MCP Servers settings, choose Configure MCP Servers, and add this entry to cline_mcp_settings.json (normally under ~/.cline/data/settings/):

{
  "mcpServers": {
    "clarvivo": {
      "command": "npx",
      "args": ["-y", "@clarvivo/mcp"],
      "env": {
        "CLARVIVO_API_TOKEN": "clv_live_REPLACE_ME"
      },
      "disabled": false
    }
  }
}

See Cline configuration locations.

Visual Studio Code / GitHub Copilot

Create .vscode/mcp.json:

{
  "servers": {
    "clarvivo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@clarvivo/mcp"],
      "env": {
        "CLARVIVO_API_TOKEN": "clv_live_REPLACE_ME"
      }
    }
  }
}

One-click install with a placeholder token:

Install Clarvivo in VS Code

VS Code’s URI uses URL-encoded JSON rather than Cursor’s base64 encoding. See the VS Code MCP developer guide and configuration reference.

Zed

Open your Zed settings file and merge:

{
  "context_servers": {
    "clarvivo": {
      "command": "npx",
      "args": ["-y", "@clarvivo/mcp"],
      "env": {
        "CLARVIVO_API_TOKEN": "clv_live_REPLACE_ME"
      }
    }
  }
}

See MCP in Zed.

Generic MCP client

For clients using the common mcpServers shape:

{
  "mcpServers": {
    "clarvivo": {
      "command": "npx",
      "args": ["-y", "@clarvivo/mcp"],
      "env": {
        "CLARVIVO_API_TOKEN": "clv_live_REPLACE_ME"
      }
    }
  }
}

Node.js 20 or newer is required.

Authentication and billing errors

Every tool checks for CLARVIVO_API_TOKEN before doing work. If it is missing, the tool returns the token URL and a copy-pasteable environment variable name. The bearer token is never included in tool output or logs.

Tools also report a missing token scope by name and link directly to the API-token settings page. Payment signing secrets are dashboard-only: connect_revenue has no secret input and sends only { provider, connected: true } to Clarvivo.

Clarvivo has no free tier. If project creation returns PROJECT_LIMIT_REACHED, HTTP 402, or HTTP 403, the tool stops immediately and links to billing. It does not retry or claim the project was created.

Development

cd mcp
npm install
npm run build
npm test

Set CLARVIVO_BASE_URL=http://127.0.0.1:5000 when using a local Clarvivo server. Tests mock HTTP and never call production.

Publishing checklist

No submission happens automatically. Complete these after the package and public repository are ready:

• npm: publish clarvivo-mcp publicly, confirm the bin is executable, and test a clean npx -y @clarvivo/mcp MCP initialize handshake. Use npm provenance/2FA and inspect npm pack --dry-run first.

• Official MCP Registry: verify the io.github.cracked-collective/clarvivo namespace, publish the matching npm version first, then run mcp-publisher login, mcp-publisher validate, and mcp-publisher publish against the included server.json. The registry stores metadata, not the package. Follow the official registry quickstart.

• Smithery: authenticate with the Smithery CLI and publish a local MCP bundle (.mcpb) under the Clarvivo namespace, or publish a hosted URL if an HTTP transport is added later: smithery mcp publish <bundle.mcpb> -n clarvivo/clarvivo. Smithery’s current publisher accepts hosted URLs or MCP bundles; see Smithery CLI publishing.

• mcp.so: use the server submission form. It currently requires a public repository URL and name; the paid path is optional and advertises immediate publishing.

• PulseMCP: use the site’s Submit flow and provide the public repository, npm install command, nineteen-tool inventory, auth variable, license, and maintainer contact. Re-check the form at submission time because PulseMCP does not publish a stable submission schema.

• Glama: click Add Server in the Glama registry, submit the public GitHub repository, and add glama.json if organization ownership/metadata verification requests it. Confirm Glama can inspect all nineteen tools.

• Cursor Marketplace: package the MCP config as an Agent Plugin or Cursor Plugin with a valid plugin.json / .cursor-plugin/plugin.json, public Git repository, README, and optional committed logo; declare the token variable in the manifest schema, then submit the repository at cursor.com/marketplace/publish. Use the official submission checklist.

• awesome-mcp-servers: first ensure the Glama listing exists, then fork punkpeye/awesome-mcp-servers, add one alphabetized line in the appropriate category with repository link and concise description, and open a PR following its contribution guide.

• Additional discovery: submit the same canonical metadata to mcpservers.org, MCP Central, and mcp-marketplace.io; keep every listing pointed at the npm package and one canonical repository so versions and security notices do not drift.

For every listing, use the same name, description, repository, license, token variable, Node requirement, nineteen-tool inventory, and install snippets from this README.