Plausible Analytics MCP

plausible-mcp

快速、以隐私为先的 Plausible Analytics 模型上下文协议（MCP）服务，适用于 AI 编码 Agent 和大模型运行框架。可与 Plausible Cloud 和可自托管的 Plausible 安装无缝协作。

快速开始

使用 uvx 运行（Python）

export PLAUSIBLE_API_KEY="your_api_key_here"
uvx plausible-mcp

使用 npx 运行（Node / npm 桥接）

export PLAUSIBLE_API_KEY="your_api_key_here"
npx -y plausible-analytics-mcp

环境配置

变量	描述	默认值
PLAUSIBLE_API_KEY	你的 Plausible Stats/Sites API 令牌	必填（或通过工具的 token 参数传入）
PLAUSIBLE_BASE_URL	可自托管 Plausible 的基础 URL	https://plausible.io
DO_NOT_TRACK	设置为 1 以禁用匿名遥测	0

获取 API 密钥

1. 登录 Plausible（Cloud 或你的可自托管实例）。
2. 前往 设置（用户资料菜单） -> API 密钥。
3. 点击 + 新建密钥，将其命名为 mcp-agent，然后复制令牌。
4. 导出为 PLAUSIBLE_API_KEY="your_token"。

可用工具

工具	描述
get_aggregate_stats(site_id, date_range="30d", metrics=None, token=None)	汇总访客、页面浏览量、跳出率和会话时长
get_breakdown(site_id, property_name="event:page", date_range="30d", limit=20, token=None)	按页面、流量来源、国家/地区、浏览器、操作系统和设备细分指标
get_realtime_visitors(site_id, token=None)	显示当前网站上的活跃访客人数
get_timeseries(site_id, date_range="30d", interval="date", token=None)	提供用于生成图表的每日或每月趋势数据点
doctor(token=None)	测试 Plausible API 连通性并验证已配置的 API 令牌
skills_list()	列出动态分析操作手册和方法指南
skill_read(name)	按名称获取完整的 Markdown 操作手册（例如 plausible-overview、analytics-recipes）
check_for_updates()	检查 PyPI 是否有更新版本并查看升级命令

错误吸收标准

返回给 Agent 的错误会明确分类：

• [INPUT_FIXABLE]：参数错误（例如，拼错 site_id、维度未知）。修正参数后重试。
• [ENVIRONMENT_FIXABLE: STOP & ASK HUMAN]：API 密钥缺失、过期或未获授权。向用户提供引导式设置步骤。
• [TRANSIENT]：上游速率限制（HTTP 429）或网络故障。稍等片刻后重试。

MCP 客户端设置

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "plausible": {
      "command": "uvx",
      "args": ["plausible-mcp"],
      "env": {
        "PLAUSIBLE_API_KEY": "YOUR_PLAUSIBLE_API_KEY"
      }
    }
  }
}

或使用 npm 桥接：

{
  "mcpServers": {
    "plausible": {
      "command": "npx",
      "args": ["-y", "plausible-analytics-mcp"],
      "env": {
        "PLAUSIBLE_API_KEY": "YOUR_PLAUSIBLE_API_KEY"
      }
    }
  }
}

许可证

MIT 许可证。详情请参阅 LICENSE。