MCP Pirsch

Pirsch MCP 服务

这是一个专用于 Pirsch Analytics API v1 的只读 Model Context Protocol 服务。它使用 MCP SDK v2，每次工具调用成功后都会返回结构化结果和 JSON 文本。

要求

• Node.js 22.19.0 或更高版本
• 具有读取权限的 Pirsch OAuth API 客户端。请勿使用仅写入的访问密钥。

配置

{
  "mcpServers": {
    "pirsch": {
      "command": "npx",
      "args": ["-y", "@verygoodplugins/mcp-pirsch@latest"],
      "env": {
        "PIRSCH_CLIENT_ID": "your-read-only-oauth-client-id",
        "PIRSCH_CLIENT_SECRET": "your-oauth-client-secret",
        "PIRSCH_DEFAULT_DOMAIN_ID": "optional-default-domain-id"
      }
    }
  }
}

PIRSCH_DEFAULT_DOMAIN_ID 为可选项。未设置时，每个查询工具都必须提供 domainId；服务不会自动选取第一个可访问的域名。使用 pirsch_list_domains 安全地查找 ID。

可选的 PIRSCH_TIMEZONE 为未明确包含 timezone 的请求提供默认时区。

工具

工具	用途
pirsch_list_domains	仅列出 id、主机名、显示名称和时区。
pirsch_query_statistics	读取一个有文档说明的 v1 指标，并支持日期和筛选条件。
pirsch_list_filter_options	列出有文档说明的筛选维度允许使用的值。
pirsch_compare_periods	比较两个时间段的实际总量和访客序列。

所有工具均为只读。它们会返回符合输出架构的 structuredContent，以及与之等效的 JSON 文本块。输入错误或 API 调用失败时会使用 MCP isError: true，且不会泄露凭据或上游原始响应正文。

查询统计数据

pirsch_query_statistics 接受一个 metric、可选的 domainId，以及扁平的驼峰式筛选条件。大多数指标都需要 ISO 日期：

{
  "metric": "pages",
  "domainId": "your-domain-id",
  "from": "2026-08-01",
  "to": "2026-08-23",
  "limit": 20,
  "sort": "visitors",
  "direction": "desc"
}

服务会将 eventMetaKey、entryPath、operatingSystem 和 utmCampaign 等公开的驼峰式字段映射到 Pirsch 文档中说明的 API v1 参数名称。limit 限制为 1–100，活跃访客的 start 限制为 0–3600 秒。

指标包括总量、访客、页面和入口／退出页面、会话和页面停留时长、目标、事件和事件元数据、增长、活跃访客、时间细分、获客、浏览器／设备、地理位置、UTM、标签、关键词、漏斗、会话和会话详情。session_details 需要同时提供 visitorId 和 sessionId；特定事件的指标需要提供 event。

比较时间段

提供一个命名的 period（today、yesterday、week、lastWeek、month 或 lastMonth），或同时提供两组明确的日期范围：

{
  "domainId": "your-domain-id",
  "from": "2026-08-01",
  "to": "2026-08-07",
  "compareFrom": "2026-07-25",
  "compareTo": "2026-07-31",
  "scale": "day"
}

响应会比较 /statistics/total 并保留两组 /statistics/visitor 序列；不会通过汇总图表来估算总量。

1.0 迁移

1.0 版本有意替换了原先包含 17 个工具的接口。不提供默认别名，因为别名会让不安全的域名选择和含糊的输入行为继续存在。

旧工具	替代方案
pirsch_overview、pirsch_total、pirsch_pages、pirsch_events 及其他统计工具	使用 metric 调用 pirsch_query_statistics
pirsch_utm	使用某个 utm_* 指标调用 pirsch_query_statistics
pirsch_compare	pirsch_compare_periods
域名发现	pirsch_list_domains

输入名称现在采用扁平的驼峰式格式（domainId、compareFrom、eventMetaKey），不再使用 domain_id、嵌套的 filter 或兼容性别名。

开发

npm install
npm run typecheck
npm run lint
npm test
npm run build
npx -y @modelcontextprotocol/inspector@latest --cli node dist/index.js --method tools/list --format json

发布工作流会使用受信任发布将软件包发布到 npm，然后通过 GitHub OIDC 将同一份带标签的清单发布到 MCP Registry。本地开发和 CI 都不会发布任何内容。

支持

如需报告错误或提出功能请求，请在此代码库中提交 issue。Pirsch 相关问题最好通过 Pirsch 文档寻求解答；软件包支持由 Very Good Plugins 维护。

由 Very Good Plugins 用 🧡 打造。