{
  "markdown": "<p align=\"center\">\n  <a href=\"https://wireboard.io\">\n    <img src=\"https://wireboard.io/img/logo-blue.png\" alt=\"WireBoard\" height=\"64\">\n  </a>\n</p>\n\n<h1 align=\"center\"><code>wireboard-mcp</code></h1>\n\n<p align=\"center\">\n  Official Model Context Protocol server for <a href=\"https://wireboard.io\">WireBoard</a>.\n</p>\n\n<p align=\"center\">\n  Lets LLM agents (Claude Desktop, Cursor, VS Code, etc.) query your real-time and historical analytics in conversation. Built on top of the official <a href=\"https://www.npmjs.com/package/@wireboard/api\"><code>@wireboard/api</code></a> JavaScript SDK.\n</p>\n\n---\n\n## Install\n\nTwo ways to install, pick whichever fits your setup.\n\n### Option A: Desktop Extension (recommended for Claude Desktop users)\n\nDownload `wireboard-mcp-x.y.z.mcpb` from the [GitHub releases page](https://github.com/wireboard/mcp/releases) and double-click it. One file works on Windows, macOS, and Linux — Claude Desktop ships its own Node runtime, so there are no system dependencies to install.\n\nClaude Desktop will prompt for your WireBoard API token, store it securely in your OS keychain, and the WireBoard tools become available immediately.\n\nIf double-click doesn't open the file, install it via Claude Desktop → Settings → Extensions → Advanced Settings → **Install Extension**.\n\n### Option B: npm install (for Cursor, VS Code, headless / CI, automation)\n\n```sh\nnpm install -g @wireboard/mcp\n```\n\nRequires Node 18+. Then configure your MCP client of choice.\n\n#### Claude Desktop config\n\nEdit `claude_desktop_config.json` (Settings → Developer → Edit Config):\n\n```json\n{\n  \"mcpServers\": {\n    \"wireboard\": {\n      \"command\": \"wireboard-mcp\",\n      \"env\": {\n        \"WIREBOARD_TOKEN\": \"your_token_here\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The WireBoard tools will appear automatically.\n\n#### Cursor / VS Code / other MCP clients\n\nUse the same command + env-var pattern in your client's MCP config.\n\n## Mint a token\n\nYou need a WireBoard API token before either install path will work. Mint one at [Settings → API](https://wireboard.io/dashboard/settings/api) with the `analytics:read` ability for REST tools and `live:read` for the live snapshot tool.\n\n## What you can ask\n\nOnce configured, ask Claude things like:\n\n- \"How many visitors did my site get last week?\"\n- \"Show me the top 10 referrers for the past 30 days.\"\n- \"What's happening on my site right now?\"\n- \"Which pages under /checkout have the worst bounce rate this month?\"\n- \"How many Purchase events fired from utm_source=newsletter yesterday?\"\n- \"Compare visitor counts day by day for the past two weeks.\"\n\nClaude will pick the right tool, call it, and answer in natural language.\n\n## Available tools\n\n| Tool | What |\n| ---- | ---- |\n| `list_sites` | Every site in the account |\n| `get_account` | Token-owner identity + abilities |\n| `get_aggregate` | Period totals: visitors, pageviews, bounce rate, duration |\n| `get_timeseries` | One metric (visitors or pageviews) bucketed by hour or day |\n| `get_history` | Per-day visitors / returning / pageviews / bounce / duration |\n| `get_breakdown` | Top-N rows by dimension (country, device, browser, referrer, etc.) |\n| `get_top_urls` | Per-URL metrics with prefix / contains / exact filters |\n| `query_events` | Custom event queries with grouping and filtering |\n| `get_live_state` | Real-time snapshot (live visitor count, top pages, active sessions, etc.) |\n| `list_dimensions` | Meta: every dimension, metric, and limit the API supports |\n\nAll tools accept natural date ranges: `\"today\"`, `\"yesterday\"`, `\"last 7 days\"` (or `\"30d\"` shorthand), `\"this week\"`, `\"last week\"`, `\"this month\"`, `\"last month\"`, or explicit `\"YYYY-MM-DD..YYYY-MM-DD\"`. Always UTC.\n\n## Rate limiting\n\nThe MCP proactively caps itself at **100 requests/minute** (under the API's 120/minute limit) so LLM bursts space themselves out instead of hitting 429s. Override with the `WIREBOARD_MCP_RATE_PER_MINUTE` env var if you have a use case that needs different pacing.\n\nThe underlying SDK still auto-retries on 429 as a backstop.\n\n## Security\n\n- **Treat your token like a credential.** It has full `analytics:read` and `live:read` scope on every site in the account.\n- **Don't commit your MCP client config to a public repo with the token in it.** Use an env var or a secret manager and reference it from your config.\n- **Revoke and rotate** if a token leaks. Settings → API in your dashboard.\n\nThe MCP is read-only: it can fetch data, never modify it. The WireBoard public API itself is read-only in v1.\n\n## Logging\n\nLogs go to stderr (so they don't interfere with the MCP protocol on stdout).\n\n## Source and contributing\n\n- **npm:** [`@wireboard/mcp`](https://www.npmjs.com/package/@wireboard/mcp)\n- **Repository:** [`github.com/wireboard/mcp`](https://github.com/wireboard/mcp)\n- **Releases (.mcpb downloads):** [`github.com/wireboard/mcp/releases`](https://github.com/wireboard/mcp/releases)\n- **Issues:** [`github.com/wireboard/mcp/issues`](https://github.com/wireboard/mcp/issues)\n- **Underlying SDK:** [`@wireboard/api`](https://www.npmjs.com/package/@wireboard/api) ([source](https://github.com/wireboard/api-js))\n- **WireBoard docs:** <https://wireboard.io/docs/api-overview>\n\n### Building locally\n\n```sh\nnpm install\nnpm test               # run vitest\nnpm run build          # bundle TS → dist/index.js (esbuild, ~600 KB)\nnpm run build:mcpb     # also pack dist/wireboard-mcp-<version>.mcpb\n```\n\nThe `.mcpb` is a zip of `manifest.json`, `icon.png`, and the single bundled `dist/index.js`. All runtime dependencies are inlined by esbuild.\n\n## License\n\n[MIT](./LICENSE).\n",
  "bytes": 5593,
  "sha": "5cbbd52bfb4bff989142201a92cc5cd903e22833690815e0fd05b90c7bacbb7e",
  "repo_slug": "wireboard/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_wireboard_mcp_7fd0355e/readme"
}