plausible-mcp

一个 MCP 服务器，让组织中的每个人都能在 Claude 中直接查询 Plausible Analytics。

一次部署即可服务整个组织。它在服务端保存一个 Plausible API 密钥，并通过 Google 对每个人进行验证，因此没有人需要自己的密钥，也无需一个人一个人地授予访问权限：把你的 Google Workspace 域名放入 ALLOWED_DOMAINS，任何使用该域名地址的人都能在第一次尝试时就连接上。该域名之外的同事则放入 ALLOWED_EMAILS，一次添加一个地址。

如果你为一个团队管理分析数据，又希望他们自己去查看这些数字，而不是来找你索取，那么这个服务器正是为此而生。

身份验证的工作原理

Claude 会通过 OAuth 2.1 动态客户端注册向此服务器注册自己。Google 不支持动态客户端注册，因此此服务器充当自己的授权服务器，并将用户的登录委托给上游的 Google。

Google 负责确认这个人是谁，但不决定他们能否阅读你的分析数据。一个中间件会在每次工具调用时，将调用者的已验证邮箱地址与 ALLOWED_DOMAINS 和 ALLOWED_EMAILS 进行核对。如果这两项都没有设置，服务器会拒绝启动。

ALLOWED_DOMAINS 正是让方案面向整个组织生效的关键：它精确匹配已验证地址的域名，所以 example.com 会接受 alice@example.com，但不会接受 alice@evil-example.com 或 alice@example.com.evil.com。

要撤销某个人的权限，将其从 ALLOWED_EMAILS 或 ALLOWED_DOMAINS 中移除，然后重新部署即可。暂停其 Google 账号可以阻止他再次登录，但允许列表读取的是此服务器签发令牌中的声明，因此已被签发的令牌在过期前仍然有效。轮换 JWT_SIGNING_KEY 会让所有令牌同时失效，代价则是所有人都要重新登录。

Related MCP server: Plausible MCP

工具

• query 运行一条 Stats API v2 查询。按不同维度分组，就能在同一个工具中得到时间序列、明细和目标转化。要比较两个时段，请为每个时段分别调用一次。

• list_sites 返回可作为 site_id 传递的站点域名列表。

• usage_stats 报告谁使用过这个服务器、使用频率如何，以及哪些账号被拒绝过。

使用情况追踪

按 allowlist 过滤的中间件必须检查每个调用者的邮箱地址，因此它也会记录起来。它会记录每人的调用次数、首次看到的时间和最后看到的时间，以及按工具划分的统计明细，写入 USAGE_PATH 指定的存储卷。被拒绝的账号会单独统计，这样你就能发现允许列表之外有人在尝试连接。

通过 usage_stats 工具读取这些数据。允许列表上的任何人都能看到所有人的记录。取消设置 USAGE_PATH 即可关闭追踪。

配置

同样的列表，可直接复制粘贴的版本见 .env.example。

部署

仓库自带 fly.toml，因此下面的说明针对 Fly.io，但服务器本身没有任何 Fly 专属的内容：它只是一个容器，需要可写目录和上述环境变量。以下所有步骤中，请把 YOUR-APP 替换为你的应用名。

1. 在 Google Cloud 控制台中创建一个 OAuth 客户端。选择 Web 应用，并将授权重定向 URI 设置为 https://YOUR-APP.fly.dev/auth/callback。该 URI 必须完全匹配。

2. 创建应用及其存储卷：

   fly apps create YOUR-APP --org YOUR-ORG
   fly volumes create plausible_mcp_data --app YOUR-APP --region fra --size 1 --yes

   请使用 fly apps create，而不是 fly launch，因为 fly launch 会重新生成 fly.toml，并丢弃现有的存储卷挂载和健康检查配置。

3. 将 fly.toml 中的 app 字段指向你的应用名。

4. 设置配置。BASE_URL 和 ALLOWED_DOMAINS 放在这里而不是 fly.toml，因为它们因部署而异；而如果提交到仓库的是占位符，下次部署时就会覆盖真实值：

   fly secrets set --app YOUR-APP \
     BASE_URL=https://YOUR-APP.fly.dev \
     ALLOWED_DOMAINS=your-domain.org \
     GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com \
     GOOGLE_CLIENT_SECRET=GOCSPX-xxx \
     PLAUSIBLE_API_KEY=xxx \
     JWT_SIGNING_KEY="$(openssl rand -hex 32)"

   保持 JWT_SIGNING_KEY 稳定：更改它会让所有人重新登录。

5. fly deploy --ha=false

   如果不带 --ha=false，Fly 可能会启动多台机器。多台机器各自使用自己的存储卷，因此在一台机器上登录成功的会话，在下一次请求落到另一台机器时就会失败。

添加到 Claude

要将其添加到整个团队，请在 claude.ai 中前往 设置 > 连接器，选择 添加自定义连接器，然后输入 https://YOUR-APP.fly.dev/mcp。每个人在第一次使用时都会用 Google 登录。

要添加到 Claude Code：

claude mcp add --transport http plausible https://YOUR-APP.fly.dev/mcp

在本地运行

uv venv && uv pip install -r pyproject.toml
cp .env.example .env    # then fill it in
set -a && source .env && set +a
python server.py

将 http://localhost:8000/auth/callback 添加到 Google 客户端的重定向 URI 中，以便在本地测试登录流程。

用 python test_server.py 运行测试。要手动操作 OAuth 流程和这些工具，请使用 npx @modelcontextprotocol/inspector。

许可证

MIT — 参见 LICENSE。