如何通过 MCP 将 PostHog 连接到 Gemini

💡 无需安装? 直接使用 cloud.anythingmcp.com。 登录、点击 Connectors → PostHog、粘贴凭证、生成 MCP API key，即可完成。无 Docker、无 git clone、无本地服务器。

PostHog + Gemini

让你的 AI 基于 PostHog 回答产品分析问题：对事件和用户运行只读 SQL（HogQL），计算趋势、漏斗和留存，读取已保存的洞察和看板，查找用户、群组、注释和实验，并管理洞察和功能开关。支持 PostHog Cloud（US 或 EU）或自托管实例，使用个人 API 密钥。

前提条件

完整的设置说明已内置在连接器中 (在 store 中选择连接器时可见)。所需环境变量:

POSTHOG_HOST, POSTHOG_PERSONAL_API_KEY

步骤 1 — 获取凭证

1. 在 PostHog 中打开 Settings → User → Personal API keys（US Cloud：https://us.posthog.com/settings/user-api-keys，EU Cloud：https://eu.posthog.com/settings/user-api-keys），点击 + Create a personal API key。
2. 为密钥设置标签（例如 "AnythingMCP"），并选择 organization and project access：全部、某一个组织或指定项目。仅限指定项目的密钥无法列出组织或项目，但 posthog_get_current_user 仍然可用，并会显示当前项目。
3. 勾选以下权限范围：
   • user:read, organization:read, project:read
   • query:read, person:read, cohort:read, experiment:read
   • insight:read, insight:write, dashboard:read
   • feature_flag:read, feature_flag:write
   • annotation:read, annotation:write
4. 立即复制密钥：PostHog 只显示一次。密钥以 phx_ 开头（以 phc_ 开头的项目令牌在这里无效）。把它填入 POSTHOG_PERSONAL_API_KEY，不要带 Bearer 字样。
5. 将 POSTHOG_HOST 设为你打开 PostHog 时使用的地址：US Cloud 用 https://us.posthog.com，EU Cloud 用 https://eu.posthog.com，自托管则填你自己实例的地址，末尾不要带斜杠或路径。数据接收地址 us.i.posthog.com 和 eu.i.posthog.com 会被拒绝，而且密钥只在创建它的云区域内有效。然后安装连接器。
6. 先运行 posthog_get_current_user：它会显示该密钥属于哪个 PostHog 用户、当前项目以及组织下的项目。

只读配置：创建密钥时只勾选 :read 权限范围，并关闭 posthog_create_insight、posthog_update_insight、posthog_create_feature_flag、posthog_update_feature_flag 和 posthog_create_annotation。查询永远不会修改数据，因为 HogQL 只接受 SELECT。AI 能看到和修改的内容与密钥所属用户完全一致。

安装时默认关闭：posthog_delete_insight、posthog_delete_feature_flag 和 posthog_delete_annotation。PostHog 通过 API 从不彻底删除：这些工具只是把洞察、开关或注释标记为已删除，之后可以在 PostHog 应用中恢复。被删除的开关会被关闭，检查其 key 的代码将得到 false。

项目 ID：每个项目级工具都需要 project_id，即 PostHog URL 中的数字（/project/12345/...），也可以在 Settings → Project → General 中找到。@current 也可以使用，但它指的是用户在应用中最后打开的项目，可能随时变化：建议使用数字。其他项目可通过 posthog_list_organizations 和 posthog_list_projects 列出。

查询：posthog_run_hogql_query 对 events、persons、sessions 和 groups 运行一条 HogQL（PostHog 的 SQL）SELECT 语句；属性用 properties.$browser 或 person.properties.email 的方式读取。请始终按时间过滤（例如 WHERE timestamp >= now() - INTERVAL 7 DAY）：不加过滤的扫描很慢，还会消耗读取预算。不加 LIMIT 时返回 100 行，加上后最多 50,000 行。OFFSET 会被拒绝，因此 AI 按 timestamp 或 id 分页。日期按项目时区解析，而不是 UTC。趋势、漏斗、留存、粘性、生命周期和路径分析使用 posthog_run_insight_query；转化率和留存率根据 count 值计算。查询接口用于即席分析，不适合批量导出。

洞察、看板和开关：posthog_get_insight 默认返回最近一次缓存的结果；refresh 设为 blocking 时会重新计算过期结果。posthog_get_dashboard 返回看板的卡片及其洞察。功能开关决定真实用户看到的内容：在创建或修改开关之前，AI 会向你展示开关的 key、active 和发布比例，并等待你确认。新开关最安全的做法是 active 设为 false 或发布比例设为 0。修改时会带上最近一次读取到的 version，以免覆盖他人的改动。

分页：列表类工具接受 limit 和 offset，返回 count、next（最后一页为 null）和 results。超过 200 KB 的响应会被截断。

速率限制：按组织计算，所有密钥和用户共享。普通读写为每分钟 480 次、每小时 4,800 次；用户查询和洞察计算等分析接口为每分钟 240 次、每小时 1,200 次。查询接口为每分钟 240 次、每小时 2,400 次，每个项目最多同时运行 3 个查询，并消耗每个项目的每小时读取预算（免费套餐更少）。超出限制时 PostHog 返回 429；预算用尽时返回 api_queries_budget_exceeded，但缓存的结果仍可使用。

常见错误：401 表示密钥错误、已删除或属于另一个云区域：请检查 POSTHOG_HOST。403 "API key missing required scope" 会指出需要添加的权限范围（密钥的权限范围之后可以修改）；其他 403 表示密钥仅限其他项目或组织，或者组织不允许成员使用个人 API 密钥。404 "Project not found." 表示 project_id 错误或该用户无权查看。400 会指出无效字段，HogQL 查询还会附带解析器错误。开关返回 409 表示其 version 已过期：请重新读取该开关。

连接器不会发送事件或设置用户属性，不会删除用户，不读取会话回放或问卷，不创建或编辑看板、群组和实验，也不管理批量导出、成员和账单。

步骤 2 — 安装 adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

步骤 3 — 在 Gemini 中添加连接器

你的服务器 URL： 在 AnythingMCP 中打开 MCP Servers → 此连接器所在的服务器，复制它的 URL（https://cloud.anythingmcp.com/mcp/…）。本指南中出现 YOUR_SERVER_ID 的地方都用它替换。

Gemini CLI 从 ~/.gemini/settings.json（Windows 上为 %USERPROFILE%\.gemini\settings.json）读取 MCP 服务器。添加：

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. 在 AnythingMCP 的 MCP Servers → 你的服务器 → API keys 中创建 MCP API 密钥，并用它替换 YOUR_MCP_API_KEY。
2. 保存文件并重启 gemini。
3. 在 Gemini CLI 中运行 /mcp（或在终端运行 gemini mcp list），anythingmcp 应显示为已连接。
4. 开始输入提示，Gemini CLI 现在可以调用 PostHog 的工具。

可用工具

示例提示

• “上周每天有多少独立用户访问了我们的价格页面？他们用的是哪些浏览器？”
• “过去 30 天里，我们的注册漏斗从浏览价格页面到完成结账的转化率是多少？”
• “现在哪些功能开关处于开启状态？每个开关的发布比例是多少？”
• “在我们的主项目中添加一条今天的注释：春季活动已上线。”

FAQ

Gemini CLI 从哪里读取 MCP 服务器？ 用户级配置位于 ~/.gemini/settings.json，项目级配置位于项目内的 .gemini/settings.json。gemini mcp list 会列出每个服务器及其连接状态。

下一步

• 连接器主页
• 连接到 Claude
• 连接到 ChatGPT