WireBoard

wireboard-mcp

WireBoard 的官方 Model Context Protocol 服务。

让大模型 Agent（Claude Desktop、Cursor、VS Code 等）在对话中查询实时和历史分析数据。基于官方 @wireboard/api JavaScript SDK 构建。

---

安装

有两种安装方式，选择适合你的方式即可。

选项 A：桌面扩展（推荐 Claude Desktop 用户使用）

从 GitHub 发布页面 下载 wireboard-mcp-x.y.z.mcpb 并双击。一个文件即可在 Windows、macOS 和 Linux 上运行——Claude Desktop 自带 Node 运行时，因此无需安装系统依赖。

Claude Desktop 会提示你输入 WireBoard API 令牌，将其安全地存储在操作系统密钥链中，随后即可立即使用 WireBoard 工具。

如果双击无法打开文件，请通过 Claude Desktop → Settings → Extensions → Advanced Settings → Install Extension 安装。

选项 B：npm 安装（适用于 Cursor、VS Code、无头环境 / CI、自动化）

npm install -g @wireboard/mcp

需要 Node 18+。然后配置你选择的 MCP 客户端。

Claude Desktop 配置

编辑 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "wireboard": {
      "command": "wireboard-mcp",
      "env": {
        "WIREBOARD_TOKEN": "your_token_here"
      }
    }
  }
}

重启 Claude Desktop。WireBoard 工具将自动显示。

Cursor / VS Code / 其他 MCP 客户端

在客户端的 MCP 配置中使用相同的命令 + 环境变量模式。

创建令牌

使用任一种安装方式前，都需要 WireBoard API 令牌。在 Settings → API 中创建令牌，并为 REST 工具授予 analytics:read 权限，为实时快照工具授予 live:read 权限。

可以询问什么

配置完成后，可以向 Claude 提问，例如：

• “上周我的网站有多少访客？”
• “列出过去 30 天的前 10 个引荐来源。”
• “我的网站现在是什么情况？”
• “本月 /checkout 下哪些页面的跳出率最高？”
• “昨天有多少 Purchase 事件来自 utm_source=newsletter？”
• “比较过去两周每天的访客数。”

Claude 会选择合适的工具并调用它，然后用自然语言作答。

可用工具

工具	说明
list_sites	账户中的所有网站
get_account	令牌所有者身份 + 权限
get_aggregate	时段汇总：访客数、页面浏览量、跳出率、停留时长
get_timeseries	按小时或按天统计的单项指标（访客数或页面浏览量）
get_history	每日访客数 / 回访访客数 / 页面浏览量 / 跳出率 / 停留时长
get_breakdown	按维度列出前 N 项（国家、设备、浏览器、引荐来源等）
get_top_urls	每个 URL 的指标，支持前缀 / 包含 / 精确匹配筛选
query_events	自定义事件查询，支持分组和筛选
get_live_state	实时快照（实时访客数、热门页面、活跃会话等）
list_dimensions	元信息：API 支持的所有维度、指标和上限

所有工具都接受自然语言日期范围："today"、"yesterday"、"last 7 days"（或简写 "30d"）、"this week"、"last week"、"this month"、"last month"，或明确的 "YYYY-MM-DD..YYYY-MM-DD"。始终使用 UTC。

速率限制

MCP 会主动将自身请求速率限制在 每分钟 100 次（低于 API 每分钟 120 次的限制），以便错开大模型的突发请求，避免触发 429 错误。如有需要采用不同请求节奏的使用场景，可通过 WIREBOARD_MCP_RATE_PER_MINUTE 环境变量覆盖此设置。

底层 SDK 仍会在 429 错误时自动重试，作为兜底措施。

安全

• 将令牌视为凭证。 它在账户中的每个站点都拥有完整的 analytics:read 和 live:read 范围。
• 不要将包含令牌的 MCP 客户端配置提交到公开仓库。 请使用环境变量或密钥管理器，并在配置中引用它。
• 如果令牌泄露，请撤销并轮换令牌。前往控制面板中的「设置 → API」。

MCP 为只读：它可以获取数据，但绝不会修改数据。WireBoard 公共 API 本身在 v1 中也是只读的。

日志记录

日志会输出到 stderr（避免干扰 stdout 上的 MCP 协议）。

源码与贡献

• npm： @wireboard/mcp
• 仓库： github.com/wireboard/mcp
• 发行版（.mcpb 下载）： github.com/wireboard/mcp/releases
• 问题反馈： github.com/wireboard/mcp/issues
• 底层 SDK： @wireboard/api (源码)
• WireBoard 文档： https://wireboard.io/docs/api-overview

本地构建

npm install
npm test               # run vitest
npm run build          # bundle TS → dist/index.js (esbuild, ~600 KB)
npm run build:mcpb     # also pack dist/wireboard-mcp-<version>.mcpb

.mcpb 是一个 zip 文件，包含 manifest.json、icon.png 和单个打包后的 dist/index.js。所有运行时依赖都由 esbuild 内联。

许可证

MIT。