plausible-mcp

用于 Plausible Analytics 的 MCP 服务器 — 从任何支持 Model Context Protocol 的 AI 工具查询流量、转化率，并比较时间段。

专为想要提出以下问题的团队而构建：

• “我们周二部署是否影响了 /pricing 的流量？”

• “本月 /blog 的注册转化率是多少？”

• “本周的跳出率与上周相比如何？”

工具

所有查询工具均为只读，并标注了 readOnlyHint: true。

托管部署还公开了 send_feedback，它将关于服务器本身的反馈（令人困惑的错误、缺失的功能）提交到维护者的 Sentry User Feedback 收件箱。仅当服务器使用 Sentry 运行时（enableFeedbackTool）才会注册该工具。

Related MCP server: umami-mcp-server

快速开始

远程（托管）

托管实例位于 https://plausible-mcp.sentry.dev。

使用您自己的 Plausible API 密钥（任何用户）：

claude mcp add --transport http plausible https://plausible-mcp.sentry.dev/mcp --header "Authorization: Bearer YOUR_PLAUSIBLE_API_KEY"

将 URL 放在 --header 之前。--header 是可变参数，如果放在最后，它会吞掉 URL，CLI 会失败并显示 error: missing required argument 'commandOrUrl'。

或者手动添加到您的 MCP 客户端配置（Claude Desktop、Cursor 等）：

{
  "mcpServers": {
    "plausible": {
      "url": "https://plausible-mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PLAUSIBLE_API_KEY"
      }
    }
  }
}

Sentry 员工（通过 OAuth 2.1 + Cloudflare Access）：

/internal 端点是 OAuth 2.1 服务器 — 无需 API 密钥。将其作为远程/自定义连接器添加到任何支持 OAuth 的 MCP 客户端（Cowork、Claude.ai 连接器、Claude Desktop）：

https://plausible-mcp.sentry.dev/internal

客户端会自动发现 OAuth 端点，将您引导通过 Sentry SSO（Cloudflare Access），并且只有 @sentry.io 身份被授予访问权限。查询使用共享的服务器端 Plausible API 密钥运行 — 您无需处理密钥。

位于 plausible-mcp.sentry.dev 的托管 /internal 仅限 Sentry 使用，不能在组织外部使用。要为其他组织运行 /internal，请自托管并将 ALLOWED_EMAIL_DOMAIN 设置为您自己的域名。（公共的 /mcp 自带密钥端点没有此类限制。）

本地（STDIO）

如果您希望本地运行，请使用 Node.js 20 或更高版本：

git clone https://github.com/getsentry/plausible-mcp.git
cd plausible-mcp
pnpm install
pnpm build

添加到 Claude Code：

claude mcp add plausible -e PLAUSIBLE_API_KEY=your-key -- node /path/to/plausible-mcp/dist/index.js

或 Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "plausible": {
      "command": "node",
      "args": ["/path/to/plausible-mcp/dist/index.js"],
      "env": {
        "PLAUSIBLE_API_KEY": "your-key"
      }
    }
  }
}

自托管（Cloudflare Workers）

部署您自己的实例：

git clone https://github.com/getsentry/plausible-mcp.git
cd plausible-mcp
pnpm install
npx wrangler deploy

该 Worker 公开两个端点：

• /mcp — 自带密钥。每个用户通过 Authorization: Bearer 标头传递自己的 Plausible API 密钥。服务器上无需共享密钥。适用于任何支持标头的 MCP 客户端（Claude Code、Cursor、MCP Inspector）。

• /internal — 用于托管连接器（Cowork、Claude.ai）的受 Access 保护的 MCP 端点。一个带有 Managed OAuth 的 Cloudflare Access 应用程序位于整个 Worker 主机名之前（见下面的约束）：Access 与客户端执行 OAuth 2.1 握手，并将每个请求转发给 Worker，并带有 Cf-Access-Jwt-Assertion 标头。Worker 验证该标头，并查询共享的服务器端 Plausible API 密钥。Access 仅限于 ALLOWED_EMAIL_DOMAIN 中的电子邮件域（默认为 sentry.io）— 自托管时不与 Sentry 绑定；请将其设置为您自己的域。

由于 Managed OAuth 应用程序必须覆盖不带路径的裸主机名（Cloudflare 在启用 OAuth 时拒绝路径 — domain can not have a path if oauth is configured），它也会限制 /mcp。为了保持自带密钥的 /mcp 端点公开，您需要添加一个第二个、更具体的 Access 应用程序，其作用域为 /mcp 路径，并带有 Bypass 策略。Cloudflare 首先匹配最具体的主机名+路径，因此 /mcp 请求完全绕过 Access，而其他所有请求都通过 OAuth。两个应用程序位于同一主机名上；无需单独的子域。

Beta / 客户端要求。 Cloudflare Access Managed OAuth 处于 Beta 阶段，要求 MCP 客户端支持 RFC 8707（资源指示符）。在依赖此路径之前，请确认您的连接器支持它。

设置 /internal 端点（Cloudflare Access Managed OAuth）

Worker 不运行 OAuth 服务器 — Cloudflare Access 是授权服务器。没有 OAUTH_KV，没有 cookie 密钥，也没有 OAuth 客户端 ID/密钥。您需要在同一主机名上创建两个 Access 应用程序。

1. 在裸主机名上创建 Managed OAuth 应用程序（Zero Trust → Access → Applications）：一个自托管应用程序或 MCP 服务器应用程序，其域为 plausible-mcp.sentry.dev 且不带路径。

   • ⚠️ 不要将其作用域限定为 /internal。 一旦启用 Managed OAuth，Cloudflare 会拒绝任何路径，并显示 access.api.error.invalid_request: domain can not have a path if oauth is configured。应用程序必须是整个主机；Worker 自身强制执行 /internal 路由。

   • 添加一个 Access 策略（操作 Allow），限制为您的电子邮件域（例如 @acme.com）和身份提供者。

   • 启用 Managed OAuth（高级设置 → Managed OAuth），并将 Allowed redirect URIs 设置为您的连接器的实际回调 — 对于 Claude/Cowork，即 https://claude.ai/api/mcp/auth_callback。公共 HTTPS 回调必须列出，否则动态客户端注册会失败，并显示 invalid_client_metadata: redirect_uri is not allowed by the account configuration；默认允许环回（http://localhost:*）回调。

   • 复制应用程序的 AUD 标签 → 这将成为 CF_ACCESS_AUD。

2. 使用第二个、路径作用域的 Bypass 应用程序将 /mcp 重新分离出来。 由于步骤 1 覆盖了整个主机，/mcp（自带密钥）现在也被限制了。创建另一个自托管应用程序，域为 plausible-mcp.sentry.dev 路径 mcp，Managed OAuth 关闭，并设置一个策略，其操作为 Bypass，选择器为 Everyone。

   • Bypass ≠ Allow：Allow 策略仍会强制交互式登录（客户端会收到 HTML 302 重定向到登录页面，并以 Unexpected content type: text/html 失败）。只有 Bypass 允许请求无需身份验证即可通过，因此 Worker 自身的 Bearer 密钥检查生效。

3. 设置 Worker 密钥：

   npx wrangler secret put PLAUSIBLE_API_KEY          # shared key for /internal queries
   npx wrangler secret put SENTRY_DSN                 # optional — the Worker's own telemetry

   CF_ACCESS_TEAM_DOMAIN 和 CF_ACCESS_AUD 不是密钥 — 它们是公共 JWKS URL 和应用程序标识符 — 因此它们放在步骤 4 的 [vars] 中。

4. 在 wrangler.toml 中设置 [vars]：

   • CF_ACCESS_TEAM_DOMAIN — https://<team>.cloudflareaccess.com，不带尾部斜杠。验证 Cf-Access-Jwt-Assertion JWKS 和签发者。

   • CF_ACCESS_AUD — 您在步骤 1 中复制的 AUD 标签。

   • ALLOWED_EMAIL_DOMAIN — 允许登录的电子邮件域，逗号分隔，@ 可选（默认 sentry.io）。在代码中除了步骤 1 中的 Access 策略之外强制执行，因此请将其设置为您自己的域 — 否则每次登录都会被拒绝。

   • MCP_ALLOWED_HOSTNAMES — MCP 端点接受的主机名，逗号分隔。将 plausible-mcp.sentry.dev 替换为您的 Worker 主机名；如果使用 wrangler dev，请保留 localhost 条目。

   • MCP_ALLOWED_ORIGIN_HOSTNAMES — 允许调用 /internal 的浏览器 Origin 主机名，逗号分隔。非浏览器客户端不会发送 Origin 标头。

5. 部署（npx wrangler deploy），然后将支持 RFC 8707 的 MCP 客户端指向 https://<your-worker-host>/internal。

故障排除。 这些都是 Cloudflare Access 配置，而不是 Worker — 请求只有在 Access 转发后才会到达 Worker（及其 Sentry spans）：

配置

在 Worker 上，/mcp 端点不需要服务端密钥 — 每个用户通过 Authorization: Bearer 传入自己的密钥。/internal 端点由 Cloudflare Access Managed OAuth 提供前置保护，并使用共享的服务端 PLAUSIBLE_API_KEY 密钥（参见自托管）。

Plausible API

此服务器封装了 Plausible Stats API v2（POST /api/v2/query）。它同时适用于 Plausible Cloud 和自托管实例。

支持的指标

visitors、visits、pageviews、views_per_visit、bounce_rate、visit_duration、events、scroll_depth、percentage、conversion_rate、group_conversion_rate、average_revenue、total_revenue、time_on_page

支持的维度

event:page、event:goal、event:hostname、visit:entry_page、visit:exit_page、visit:source、visit:referrer、visit:channel、visit:utm_medium、visit:utm_source、visit:utm_campaign、visit:utm_content、visit:utm_term、visit:device、visit:browser、visit:browser_version、visit:os、visit:os_version、visit:country、visit:region、visit:city、visit:country_name、visit:region_name、visit:city_name

*_name 地理维度返回人类可读的名称（例如“加拿大”）；普通的 visit:country/region/city 返回 ISO/Geoname 代码。

过滤

每个查询工具都接受 property_filters，尽管名称如此，它既可以按内置维度过滤，也可以按自定义事件属性过滤。每个条目为 { "property", "operator", "values" }：

• property — 内置维度（例如 visit:channel、visit:source、event:page）或以其裸名称表示的自定义属性（"plan" 对应 event:props:plan）。

• operator — is、is_not、contains、contains_not（默认为 is）。event:goal 仅支持 is 和 contains。

• 多个条目之间以 AND 组合，page/goal 快捷参数也是如此。在同一调用中同时通过快捷参数和 property_filters 指定 event:page/event:goal 会被拒绝 — 请二选一。

例如，获取自然搜索流量的热门页面：使用 dimension: "event:page" 和 property_filters: [{ "property": "visit:channel", "values": ["Organic Search"] }] 调用 get_breakdown。

自定义属性

站点会发送自己的自定义事件属性，以 event:props:<name> 的形式寻址。这些属性因站点而异，因此没有固定的列表。

• 按自定义属性细分：向 get_breakdown 传入 event:props:<name> 作为 dimension（例如 event:props:plan）。

• 按自定义属性过滤：通过 property_filters 使用裸名称，例如 [{ "property": "plan", "operator": "is", "values": ["pro"] }]。

开发

pnpm install
pnpm build         # TypeScript compilation
pnpm test          # Run unit + integration tests
pnpm test:watch    # Watch mode

使用 MCP Inspector 测试

pnpm build
PLAUSIBLE_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js

LLM 评估

验证模型能否为自然语言分析问题选择正确的工具。通过 OpenRouter 运行，因此任何支持工具调用的模型都可以使用 — 默认为 anthropic/claude-sonnet-5：

OPENROUTER_API_KEY=sk-or-... pnpm eval
OPENROUTER_MODEL=openai/gpt-5 OPENROUTER_API_KEY=sk-or-... pnpm eval  # try another model

架构

src/
├── index.ts              # STDIO entry point (local use)
├── worker.ts             # Cloudflare Worker entry point (remote)
├── env.ts                # Worker environment bindings
├── cf-access.ts          # Verifies the Cloudflare Access assertion on /internal
├── server.ts             # Creates McpServer, registers all tools
├── plausible.ts          # PlausibleClient — standalone API client
├── schemas.ts            # Shared Zod schemas and filter helpers
├── errors.ts             # UserFacingError and tool-error reporting
├── telemetry.ts          # Pure classifiers — route, MCP request kind, client family
├── mcp-telemetry.ts      # Records MCP client info onto the active span
├── redaction.ts          # Strips PII from Sentry events on the BYOK path
└── tools/
    ├── get-timeseries.ts
    ├── get-breakdown.ts
    ├── get-conversions.ts
    ├── compare-periods.ts
    └── send-feedback.ts

PlausibleClient 完全不依赖 MCP，可以独立使用。

可观测性与数据收集

Worker 向 Sentry 上报数据，并根据端点采用不同的隐私策略：

• /mcp（自带密钥） — 完全匿名。工具输入和输出不会被记录（这些数据属于调用者及其自己的密钥），不附加任何身份信息，并且会剥离由 ingest 推断出的客户端 IP（src/redaction.ts）。仅保留操作层面的遥测：工具名称、span 耗时和失败信息。

• /internal（SSO 门控） — 可归因。请求携带经过认证的 @sentry.io 电子邮件（Sentry.setUser），并且工具输入/输出会被记录（recordToolIO），以便在共享的服务端密钥上进行归因和滥用追踪。

Authorization / Cookie / Cf-Access-Jwt-Assertion 头在两条路径上都会从 span 中剥离。作为双保险，请在 Sentry 项目的 Security & Privacy 设置中启用 Prevent Storing of IP Addresses（阻止存储 IP 地址）。

许可证

MIT — 参见 LICENSE。