@meertrack/mcp

Model Context Protocol server for Meertrack. Ask your agent "what did my competitors ship this week?" from Claude, Cursor, Claude Code, VS Code, Windsurf, Cline, ChatGPT, or anywhere that speaks MCP.

Wraps the Meertrack v1 REST API as 8 read-only tools and 3 prompt workflows. No backend changes, same mt_live_ keys, same rate limits.

Pick your transport

If you're on Claude Pro, use the local (stdio) path. The "Add custom connector" button in the Claude Desktop settings is gated to Team/Enterprise, and pasting https://mcp.meertrack.com/mcp there won't do anything on a Pro plan.

Get an API key

Mint a production key at Settings → API Keys in the Meertrack app. Keys start with mt_live_. Only production keys work; there is no mt_test_ flavour.

Rate limits. Each API key shares a 60 requests/minute budget enforced upstream. If you run the MCP from multiple clients at once (Claude Desktop + Cursor + a background agent) they all draw from the same bucket. Mint a separate key per workstation or per agent to isolate budgets. The tool-error message on 429 includes both a human-readable reset time and the raw X-RateLimit-Reset epoch so the agent can back off automatically.

Local install: recommended default

All local-mode clients use the same shape: npx -y @meertrack/mcp with MEERTRACK_API_KEY in the environment. What differs is the config file and the surrounding JSON key.

Drop-in copies of every config file below live in examples/.

Claude Desktop (all plans)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "meertrack": {
      "command": "npx",
      "args": ["-y", "@meertrack/mcp"],
      "env": {
        "MEERTRACK_API_KEY": "mt_live_..."
      }
    }
  }
}

Gotcha: Claude Desktop only re-reads this file on launch. Fully quit (⌘Q on macOS) and reopen. Reloading the window is not enough.

Cursor

Edit ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "meertrack": {
      "command": "npx",
      "args": ["-y", "@meertrack/mcp"],
      "env": {
        "MEERTRACK_API_KEY": "mt_live_..."
      }
    }
  }
}

Claude Code (CLI)

claude mcp add meertrack npx -y @meertrack/mcp \
  --env MEERTRACK_API_KEY=mt_live_...

VS Code (GitHub Copilot MCP)

Edit .vscode/mcp.json (per-workspace) or the user settings equivalent:

{
  "servers": {
    "meertrack": {
      "command": "npx",
      "args": ["-y", "@meertrack/mcp"],
      "env": {
        "MEERTRACK_API_KEY": "mt_live_..."
      }
    }
  }
}

Gotcha: VS Code uses servers, not mcpServers. The Copilot MCP picker won't find your server if you use the Claude Desktop key.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "meertrack": {
      "command": "npx",
      "args": ["-y", "@meertrack/mcp"],
      "env": {
        "MEERTRACK_API_KEY": "mt_live_..."
      }
    }
  }
}

Gotcha: Windsurf's remote-connector shape uses serverUrl, not url. For the stdio config above, the shape is identical to Claude Desktop.

Cline (VS Code extension)

Cline's settings panel → "MCP Servers" → paste:

{
  "mcpServers": {
    "meertrack": {
      "command": "npx",
      "args": ["-y", "@meertrack/mcp"],
      "env": {
        "MEERTRACK_API_KEY": "mt_live_..."
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Remote install: Team/Enterprise + claude.ai web

All remote clients point at the same URL:

https://mcp.meertrack.com/mcp

Two auth paths are supported:

• OAuth 2.1 (recommended) — spec-conformant MCP clients discover the authorization server at /.well-known/oauth-protected-resource/mcp (RFC 9728 §3.1; also served at the bare /.well-known/oauth-protected-resource for clients that probe the root), perform Dynamic Client Registration at https://meertrack.com/oauth/register, and drive the full PKCE-gated authorize → token flow. The user clicks "Connect", signs in at meertrack.com, hits Allow on the consent screen, and is done. No key handling. Access tokens are 1-hour JWTs (RS256, aud=https://mcp.meertrack.com/mcp); refresh tokens are rotated per OAuth 2.1 §4.3.1.
• Authorization: Bearer mt_live_… — paste a static API key for custom connectors, CLI scripts, and any client that doesn't implement OAuth discovery yet.

Both paths terminate at the same workspace; pick whichever your client supports.

Claude Desktop (Team / Enterprise only: "Add custom connector")

Settings → Connectors → Add custom connector → paste the URL above. Do not paste a bearer token — leave the token field empty and click Add. Claude Desktop will open a browser window to meertrack.com for login and consent; on Allow, the connector surfaces the 8 tools automatically.

The "Add custom connector" button is not visible on Pro; use the stdio path above instead.

Claude.ai web (Connectors)

Same as above in the web app's Connectors panel.

Cursor (remote MCP)

{
  "mcpServers": {
    "meertrack": {
      "url": "https://mcp.meertrack.com/mcp",
      "headers": {
        "Authorization": "Bearer mt_live_..."
      }
    }
  }
}

ChatGPT MCP connectors

Paste the URL and bearer in the ChatGPT "Add MCP" dialog. Note: ChatGPT's bearer support is minimal today; full OAuth parity is tracked as Phase 11.

n8n / Zapier / …any Streamable HTTP client

• Endpoint: https://mcp.meertrack.com/mcp
• Method: POST
• Headers: Authorization: Bearer mt_live_…, Accept: application/json, text/event-stream, MCP-Protocol-Version: 2025-11-25

The 8 tools

All read-only, all snake_case. Collection returns use the list_ prefix; row-detail returns use get_ (single id or a batch of ids). Every list response includes pagination.next_cursor and pagination.has_more, and agents must pass next_cursor back as cursor to fetch the next page.

Full input / output / error-code documentation is on the tool descriptions themselves, and the MCP client displays them inline.

The 3 prompts

Slash commands in Claude Desktop / Cursor / Claude Code / any prompt-capable MCP client. Each one chains tool calls into a complete workflow.

Example invocations

• /weekly_recap
• /competitor_deep_dive competitor_name="Acme"
• /whats_new days="14"

See examples/prompts.md for a dozen copy-paste user prompts grouped by use case (weekly check-in, feature spec research, pricing comparison, board-deck prep).

Troubleshooting

When the upstream API returns an error, the MCP tool response surfaces the upstream code in the error text. Map them:

Other common snags

• Claude Desktop didn't pick up your config → quit and relaunch the app, not just close the window. Config is read at launch.
• command not found: npx → install Node ≥ 20. The MCP pins engines.node.
• Remote URL returns 401 with WWW-Authenticate: Bearer → your bearer is missing, malformed, or doesn't start with mt_live_.
• You see 401s that clear up when you refresh the key → the bearer is fine; this is a spec-conformant "please authenticate" from the MCP. Send the Authorization header.
• Running both stdio and remote with the same key → you're sharing a 60/min budget across both. Mint separate keys per client.

Semantic versioning

MCP tool schemas are part of the public API contract; agents cache them. So:

• MAJOR: a tool is removed, or an existing tool's input/output schema breaks (required arg added, field renamed, enum value removed).
• MINOR: a new tool, a new optional argument, or a new prompt.
• PATCH: bug fixes, description improvements, internal refactors with no schema impact.

See CHANGELOG.md for the release history, and docs/RELEASING.md for the maintainer publish procedure.

Security & privacy

• Privacy policy: https://meertrack.com/privacy
• SECURITY.md: disclosure policy (security@meertrack.com), in-scope surface.
• docs/PRIVACY.md: the MCP layer is stateless; bearers are forwarded per-request and nothing is persisted.
• docs/ARCHITECTURE.md: request flow diagram.
• docs/OBSERVABILITY.md: what gets logged, and how bearer tokens are redacted.

License

MIT.