{
  "markdown": "# `@meertrack/mcp`\n\n[![MCP protocol 2025-11-25](https://img.shields.io/badge/MCP-2025--11--25-5e5edd)](https://modelcontextprotocol.io/specification/2025-11-25)\n[![8 tools · 3 prompts](https://img.shields.io/badge/tools-8%20%C2%B7%20prompts%203-10b981)](#the-8-tools)\n[![npm](https://img.shields.io/npm/v/@meertrack/mcp.svg)](https://www.npmjs.com/package/@meertrack/mcp)\n[![CI](https://github.com/meertrack/meertrack-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/meertrack/meertrack-mcp/actions/workflows/ci.yml)\n\nModel Context Protocol server for [Meertrack](https://meertrack.com). Ask your\nagent \"what did my competitors ship this week?\" from Claude, Cursor, Claude\nCode, VS Code, Windsurf, Cline, ChatGPT, or anywhere that speaks MCP.\n\nWraps the [Meertrack v1 REST API](https://meertrack.com/developers/api) as **8\nread-only tools** and **3 prompt workflows**. No backend changes, same\n`mt_live_` keys, same rate limits.\n\n---\n\n## Pick your transport\n\n| | Local (stdio) | Remote (Streamable HTTP) |\n| --- | --- | --- |\n| **Setup time** | 30 seconds (paste a JSON block) | 10 seconds (paste a URL) |\n| **Best for** | Individual Pro customers; all Claude Desktop plans; any IDE on your laptop | Team/Enterprise custom connectors; Claude.ai web; remote-capable IDEs |\n| **Runs where** | Your machine (`npx -y @meertrack/mcp`) | Meertrack's Fly.io fleet (`https://mcp.meertrack.com/mcp`) |\n| **Auth** | `MEERTRACK_API_KEY` env var | OAuth 2.1 (browser flow, recommended) or `Authorization: Bearer mt_live_…` header |\n| **Plan gating** | Works on Claude Pro, Team, Enterprise | Claude Desktop \"Add custom connector\" is **Team/Enterprise only** |\n\n**If you're on Claude Pro, use the local (stdio) path.** The \"Add custom\nconnector\" button in the Claude Desktop settings is gated to Team/Enterprise,\nand pasting `https://mcp.meertrack.com/mcp` there won't do anything on a Pro\nplan.\n\n## Get an API key\n\nMint a production key at **Settings → API Keys** in the Meertrack app. Keys\nstart with `mt_live_`. Only production keys work; there is no `mt_test_`\nflavour.\n\n> **Rate limits.** Each API key shares a **60 requests/minute** budget enforced\n> upstream. If you run the MCP from multiple clients at once (Claude Desktop +\n> Cursor + a background agent) they all draw from the same bucket. Mint a\n> separate key per workstation or per agent to isolate budgets. The tool-error\n> message on 429 includes both a human-readable reset time and the raw\n> `X-RateLimit-Reset` epoch so the agent can back off automatically.\n\n---\n\n## Local install: recommended default\n\nAll local-mode clients use the same shape: `npx -y @meertrack/mcp` with\n`MEERTRACK_API_KEY` in the environment. What differs is the config file and\nthe surrounding JSON key.\n\nDrop-in copies of every config file below live in [`examples/`](examples/).\n\n### Claude Desktop (all plans)\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)\nor `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"meertrack\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@meertrack/mcp\"],\n      \"env\": {\n        \"MEERTRACK_API_KEY\": \"mt_live_...\"\n      }\n    }\n  }\n}\n```\n\n> **Gotcha**: Claude Desktop only re-reads this file on launch. Fully quit\n> (⌘Q on macOS) and reopen. Reloading the window is not enough.\n\n### Cursor\n\nEdit `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):\n\n```json\n{\n  \"mcpServers\": {\n    \"meertrack\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@meertrack/mcp\"],\n      \"env\": {\n        \"MEERTRACK_API_KEY\": \"mt_live_...\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code (CLI)\n\n```bash\nclaude mcp add meertrack npx -y @meertrack/mcp \\\n  --env MEERTRACK_API_KEY=mt_live_...\n```\n\n### VS Code (GitHub Copilot MCP)\n\nEdit `.vscode/mcp.json` (per-workspace) or the user settings equivalent:\n\n```json\n{\n  \"servers\": {\n    \"meertrack\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@meertrack/mcp\"],\n      \"env\": {\n        \"MEERTRACK_API_KEY\": \"mt_live_...\"\n      }\n    }\n  }\n}\n```\n\n> **Gotcha**: VS Code uses `servers`, not `mcpServers`. The Copilot MCP picker\n> won't find your server if you use the Claude Desktop key.\n\n### Windsurf\n\nEdit `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"meertrack\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@meertrack/mcp\"],\n      \"env\": {\n        \"MEERTRACK_API_KEY\": \"mt_live_...\"\n      }\n    }\n  }\n}\n```\n\n> **Gotcha**: Windsurf's remote-connector shape uses `serverUrl`, not `url`.\n> For the stdio config above, the shape is identical to Claude Desktop.\n\n### Cline (VS Code extension)\n\nCline's settings panel → \"MCP Servers\" → paste:\n\n```json\n{\n  \"mcpServers\": {\n    \"meertrack\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@meertrack/mcp\"],\n      \"env\": {\n        \"MEERTRACK_API_KEY\": \"mt_live_...\"\n      },\n      \"disabled\": false,\n      \"autoApprove\": []\n    }\n  }\n}\n```\n\n---\n\n## Remote install: Team/Enterprise + claude.ai web\n\nAll remote clients point at the same URL:\n\n```\nhttps://mcp.meertrack.com/mcp\n```\n\nTwo auth paths are supported:\n\n- **OAuth 2.1 (recommended)** — spec-conformant MCP clients discover the\n  authorization server at `/.well-known/oauth-protected-resource/mcp` (RFC 9728\n  §3.1; also served at the bare `/.well-known/oauth-protected-resource` for\n  clients that probe the root), perform\n  Dynamic Client Registration at `https://meertrack.com/oauth/register`, and\n  drive the full PKCE-gated authorize → token flow. The user clicks\n  \"Connect\", signs in at `meertrack.com`, hits Allow on the consent screen,\n  and is done. No key handling. Access tokens are 1-hour JWTs\n  (RS256, `aud=https://mcp.meertrack.com/mcp`); refresh tokens are rotated\n  per OAuth 2.1 §4.3.1.\n- **`Authorization: Bearer mt_live_…`** — paste a static API key for custom\n  connectors, CLI scripts, and any client that doesn't implement OAuth\n  discovery yet.\n\nBoth paths terminate at the same workspace; pick whichever your client\nsupports.\n\n### Claude Desktop (Team / Enterprise only: \"Add custom connector\")\n\nSettings → Connectors → **Add custom connector** → paste the URL above.\n**Do not paste a bearer token** — leave the token field empty and click Add.\nClaude Desktop will open a browser window to `meertrack.com` for login and\nconsent; on Allow, the connector surfaces the 8 tools automatically.\n\nThe \"Add custom connector\" button is not visible on Pro; use the stdio path\nabove instead.\n\n### Claude.ai web (Connectors)\n\nSame as above in the web app's Connectors panel.\n\n### Cursor (remote MCP)\n\n```json\n{\n  \"mcpServers\": {\n    \"meertrack\": {\n      \"url\": \"https://mcp.meertrack.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer mt_live_...\"\n      }\n    }\n  }\n}\n```\n\n### ChatGPT MCP connectors\n\nPaste the URL and bearer in the ChatGPT \"Add MCP\" dialog. Note: ChatGPT's\nbearer support is minimal today; full OAuth parity is tracked as Phase 11.\n\n### n8n / Zapier / …any Streamable HTTP client\n\n- Endpoint: `https://mcp.meertrack.com/mcp`\n- Method: `POST`\n- Headers: `Authorization: Bearer mt_live_…`, `Accept: application/json, text/event-stream`, `MCP-Protocol-Version: 2025-11-25`\n\n---\n\n## The 8 tools\n\nAll read-only, all snake_case. Collection returns use the `list_` prefix;\nrow-detail returns use `get_` (single id or a batch of ids). Every list response includes\n`pagination.next_cursor` and `pagination.has_more`, and agents must pass\n`next_cursor` back as `cursor` to fetch the next page.\n\n| Domain | Tool | Wraps | Notes |\n| --- | --- | --- | --- |\n| Identity | [`whoami`](src/tools/whoami.ts) | `GET /me` | Confirms workspace + subscription + rate-limit snapshot. Call first. |\n| Competitors | [`list_competitors`](src/tools/list_competitors.ts) | `GET /competitors` | Defaults to `expand=full` so agents don't round-trip for socials/pages. |\n| Competitors | [`get_competitor`](src/tools/get_competitor.ts) | `GET /competitors/{id}` | Profile + recent items from each tracked section (blog, pricing, jobs, ads, …) with per-section caps. |\n| Activity | [`list_activities`](src/tools/list_activities.ts) | `GET /activity` | Core \"what shipped\" feed. Default `limit=50` to stay under tool-result size limits. |\n| Activity | [`get_activity_items`](src/tools/get_activity_items.ts) | `GET /activity/items` | Batch drill-in: full payloads for 1–100 row ids; unresolved ids returned in `not_found`. |\n| Digests | [`list_digests`](src/tools/list_digests.ts) | `GET /digests` | Cursor-paginated weekly digests. No `total` field (unlike activity). |\n| Digests | [`list_latest_digests`](src/tools/list_latest_digests.ts) | `GET /digests/latest` | No params; one-shot \"what happened this week\". |\n| Digests | [`get_digest`](src/tools/get_digest.ts) | `GET /digests/{id}` | Full summary + themes for one competitor × period. |\n\nFull input / output / error-code documentation is on the tool descriptions\nthemselves, and the MCP client displays them inline.\n\n## The 3 prompts\n\nSlash commands in Claude Desktop / Cursor / Claude Code / any prompt-capable\nMCP client. Each one chains tool calls into a complete workflow.\n\n| Prompt | Args | Chains |\n| --- | --- | --- |\n| [`/weekly_recap`](src/prompts/weekly_recap.ts) | none | `list_latest_digests` → per-competitor summary + highlights |\n| [`/competitor_deep_dive`](src/prompts/competitor_deep_dive.ts) | `competitor_name` | `list_competitors` → `get_competitor` → `list_activities` (last 30d) |\n| [`/whats_new`](src/prompts/whats_new.ts) | `days?` (default 7) | `list_activities` from `now - N days`, grouped by competitor |\n\n### Example invocations\n\n- `/weekly_recap`\n- `/competitor_deep_dive competitor_name=\"Acme\"`\n- `/whats_new days=\"14\"`\n\nSee [`examples/prompts.md`](examples/prompts.md) for a dozen copy-paste user\nprompts grouped by use case (weekly check-in, feature spec research, pricing\ncomparison, board-deck prep).\n\n---\n\n## Troubleshooting\n\nWhen the upstream API returns an error, the MCP tool response surfaces the\nupstream `code` in the error text. Map them:\n\n| Upstream `code` | What it means | Fix |\n| --- | --- | --- |\n| `unauthorized` | Key is invalid, revoked, or expired | Mint a new key at Settings → API Keys and update the config |\n| `competitor_inactive` | Competitor is archived in this workspace | Reactivate the competitor in the dashboard |\n| `forbidden_competitor` | The `id` you passed isn't in this workspace | Call `list_competitors` first to discover valid ids |\n| `rate_limited` | 60 req/min cap hit | Wait until the reset timestamp in the error message, or mint a second key for the other client |\n| `not_found` | No such row in this workspace | The id is either wrong or belongs to a different workspace |\n| `invalid_parameter` / `invalid_cursor` | Bad input | Check the error message; cursors expire, so re-list from the start |\n\n**Other common snags**\n\n- Claude Desktop didn't pick up your config → **quit and relaunch the app**,\n  not just close the window. Config is read at launch.\n- `command not found: npx` → install Node ≥ 20. The MCP pins `engines.node`.\n- Remote URL returns 401 with `WWW-Authenticate: Bearer` → your bearer is\n  missing, malformed, or doesn't start with `mt_live_`.\n- You see 401s that clear up when you refresh the key → the bearer is fine;\n  this is a spec-conformant \"please authenticate\" from the MCP. Send the\n  `Authorization` header.\n- Running both stdio and remote with the **same key** → you're sharing a\n  60/min budget across both. Mint separate keys per client.\n\n---\n\n## Semantic versioning\n\nMCP tool schemas are part of the public API contract; agents cache them. So:\n\n- **MAJOR**: a tool is removed, or an existing tool's input/output schema\n  breaks (required arg added, field renamed, enum value removed).\n- **MINOR**: a new tool, a new optional argument, or a new prompt.\n- **PATCH**: bug fixes, description improvements, internal refactors with no\n  schema impact.\n\nSee [CHANGELOG.md](CHANGELOG.md) for the release history, and\n[docs/RELEASING.md](docs/RELEASING.md) for the maintainer publish procedure.\n\n## Security & privacy\n\n- **Privacy policy**: [https://meertrack.com/privacy](https://meertrack.com/privacy)\n- [SECURITY.md](SECURITY.md): disclosure policy (`security@meertrack.com`),\n  in-scope surface.\n- [docs/PRIVACY.md](docs/PRIVACY.md): the MCP layer is stateless; bearers are\n  forwarded per-request and nothing is persisted.\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): request flow diagram.\n- [docs/OBSERVABILITY.md](docs/OBSERVABILITY.md): what gets logged, and how\n  bearer tokens are redacted.\n\n## License\n\nMIT.\n",
  "bytes": 12493,
  "sha": "d0adbe3f56acad596ee3d19c33ae45daf910e937f74753d725f30031b9c77cea",
  "repo_slug": "meertrack/meertrack-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_meertrack_mcp_server_519868d7/readme"
}