PostHog MCP Server (Official)

什么是 PostHog MCP Server (Official)？

PostHog MCP server 是 PostHog 官方提供的免费托管 Model Context Protocol 端点（https://mcp.posthog.com/mcp），让 AI 智能体可以在你的 PostHog 项目中查询分析数据、运行 SQL、管理 feature flag 和实验，并排查错误。

它是一个远程服务器，无需在本地运行任何东西。你只需把这个 URL 添加到 Claude Code、Claude Desktop、Cursor、Codex、VS Code、Windsurf 或 Zed 等 MCP 客户端，通过 OAuth 登录 PostHog，智能体即可读写 PostHog 的各项产品。源码位于 PostHog monorepo 的 services/mcp 目录；旧的 PostHog/mcp 仓库现在只是指向那里。

如何使用 PostHog MCP Server (Official)？

你需要一个 PostHog 账号（US 或 EU Cloud）。支持 OAuth 的客户端无需 API key：智能体首次使用该服务器时会打开浏览器窗口让你登录，PostHog 认证服务器会自动把你路由到正确的数据区域。

最快的方式是使用 PostHog Wizard，它可以把 PostHog MCP server 安装到 PostHog Desktop、Cursor、Claude Code、Claude Desktop、Codex、VS Code 和 Zed：

npx @posthog/wizard mcp add

Claude Code

claude mcp add --transport http posthog https://mcp.posthog.com/mcp -s user

也可以安装 PostHog 插件，它提供相同的工具，以及 /posthog:flags、/posthog:insights、/posthog:errors 等斜杠命令：

claude plugin install posthog

安装后运行 /mcp，按照浏览器提示登录。

Claude Desktop

在 Claude 连接器目录中使用 PostHog connector，点击 Connect。如需手动配置，打开 Settings > Developer > Edit Config 并添加：

{
  "mcpServers": {
    "posthog": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.posthog.com/mcp"]
    }
  }
}

Cursor

从 Cursor Marketplace 安装 PostHog 插件，或在 Cursor Settings > Tools & Integrations > New MCP Server 中把以下内容加入 mcp.json：

{
  "mcpServers": {
    "posthog": {
      "url": "https://mcp.posthog.com/mcp"
    }
  }
}

VS Code

在命令面板中运行 MCP: Open User Configuration，然后添加：

{
  "servers": {
    "posthog": {
      "type": "http",
      "url": "https://mcp.posthog.com/mcp"
    }
  }
}

之后即可在 Copilot chat 中使用该服务器。

Codex

codex mcp add posthog --url https://mcp.posthog.com/mcp

Codex 原生支持 OAuth，首次使用时会提示你登录。

Windsurf

在 Windsurf Settings > Cascade > MCP Servers > Manage MCP Servers > View raw config 中，把上面 Claude Desktop 部分的 mcp-remote 配置块加入 mcp_config.json。

使用 API key 代替 OAuth

如果你的客户端不支持 OAuth，可以使用 MCP Server 预设创建 personal API key，并通过请求头发送：

{
  "mcpServers": {
    "posthog": {
      "url": "https://mcp.posthog.com/mcp",
      "headers": {
        "Authorization": "Bearer ${POSTHOG_API_KEY}"
      }
    }
  }
}

PostHog MCP Server (Official) 的主要功能

• 由 PostHog 官方维护，托管在单一的 Streamable HTTP 端点上。
• OAuth 登录并自动路由到 US/EU 区域；personal API key 作为备选方案。
• 覆盖分析、SQL（HogQL）、dashboard、insight、feature flag、实验、调查问卷（survey）、session replay、错误追踪、日志、CDP destination 和支持工单。
• 两种工具模式：CLI 模式只暴露一个节省 token 的 exec 工具，tools 模式则逐个注册所有工具。模式会自动检测，也可以用 ?mode=cli 或 ?mode=tools 覆盖。
• 通过 ?readonly=true 或 x-posthog-read-only 请求头开启只读会话。
• 按类别（?features=flags,dashboards,insights）或精确名称（?tools=dashboard-get,execute-sql）过滤工具。
• 通过 x-posthog-organization-id 和 x-posthog-project-id 请求头固定上下文。
• 仅作为代理：不会存储你的分析数据。

PostHog MCP Server (Official) 工具

该服务器提供数百个工具，按 PostHog 产品分组：

• 分析与 SQL：execute-sql 运行 SQL 查询，query-trends、query-funnel 等查询工具运行 insight 类查询。dashboard 工具（dashboard-get、dashboard-create、dashboards-get-all）用于读取和创建 dashboard。
• Feature flag 与实验：feature-flag-get-all、create-feature-flag、update-feature-flag、experiment-create 和 experiment-results-get 让智能体发布并评估灰度发布。
• 错误追踪：query-error-tracking-issues-list、error-tracking-issues-partial-update 等工具用于列出、查看、分配和解决问题。
• 用户与数据：persons-list、cohorts-create、session-recording-get、surveys-get-all 和 survey-create。
• 日志：query-logs 及相关日志工具，用于查询和告警。
• 工作区与文档：switch-organization、switch-project、projects-get，以及用于搜索 PostHog 文档的 docs-search。

在 CLI 模式下，智能体通过 exec 按需搜索、查看并调用这些工具；在支持 MCP apps 的客户端中，render-ui 可以绘制可视化图表。

PostHog MCP Server (Official) 的使用场景

• 在编辑器中调试线上错误：“本周我的项目中排名前 5 的错误是什么？”，然后“显示最近一次崩溃的完整堆栈跟踪，并提出修复方案。”
• 用一句话发布 feature flag：“创建一个名为 new-checkout 的 flag，向 10% 的用户开放。”
• 用自然语言或 SQL 提出产品问题：“上周有多少用户注册？按国家拆分。”
• 查看实验结果：“总结 pricing-page 实验的结果。”
• 分诊问题并指定负责人：“把这个问题标记为已解决，并把以后所有 TypeError 分配给后端团队。”
• 搭建 dashboard：“创建一个包含日活用户和注册漏斗的 dashboard。”

PostHog MCP Server (Official) 与替代方案对比

• Google Analytics MCP Server 侧重读取 GA4 报表。PostHog MCP server 还可以写入：flag、实验、dashboard 和调查问卷。
• Sentry MCP Server (Official) 专注于错误监控。PostHog 在一个连接中同时提供错误追踪和产品分析。
• Grafana MCP Server (Official) 面向可观测性 dashboard 和指标，而非产品分析。

PostHog MCP Server (Official) 常见问题排查

• 客户端不支持 OAuth：在 Authorization: Bearer 请求头中使用带 MCP Server 预设的 personal API key，或使用 mcp-remote 桥接。
• 智能体写入了错误的项目：用 x-posthog-project-id 固定连接（这也会移除 switch-* 工具），或为每个项目添加一个单独命名的服务器条目。
• 两个账号或两个区域：每个账号添加一个独立连接。在共享浏览器会话中使用 OAuth 时，很容易把两个连接都授权给同一个账号；为每个条目使用单独的 API key 可以避免这种情况。
• 工具太多或占用上下文过多：使用 CLI 模式（?mode=cli），或通过 features/tools 过滤。
• AI 驱动的工具不见了：只有在组织设置中启用 AI 数据处理后，这些工具才会出现。