PostHog MCP 与 Claude Code 接入指南
用 PostHog MCP 在 Claude Code 中关联事件与上报代码并检验假设；核对项目、时间窗口与隐私边界。
PostHog MCP 如何改变 Claude Code 的调查方式
PostHog MCP 让 Claude Code 在同一次调查中把产品行为与实现上下文联系起来。与其把一张图表复制进提示词，智能体可以读取获准的 PostHog 资源，定位产生这些数据的事件上报或功能开关代码，检验假设，再提出范围明确的补丁。但连接成功并不代表分析结论自动正确；项目选择、事件定义、身份归并、时区、筛选条件和查询周期，仍然决定数字应该如何解释。
写清行为、用户范围、时间窗口、对照组和要支持的决策。“激活率为什么下降”只是主题；按人群拆分的周同比漏斗问题才可检验。
查询前记录 PostHog 主机、组织、项目、时区和环境。相似项目名可能返回看起来可信、实际完全错误的结果。
既从事件找到上报代码，也从上报代码反查实际事件，才能发现命名漂移、属性缺失和重复埋点。
探索阶段保持只读。修改功能开关、实验、Annotation、Dashboard 或项目配置，应视为不同动作并分别审查。
安装当前 PostHog MCP 集成
PostHog 早期独立 MCP 仓库已经归档，因为服务器已迁入 PostHog 主仓库。新配置不要再照搬旧仓库片段。PostHog 目前把用户引导至产品文档，并提供向 Claude Code 等客户端添加 MCP 集成的安装向导。
先确定工作区使用 PostHog Cloud US、Cloud EU，还是获批的自托管部署。身份验证和项目发现必须指向同一主机。
PostHog 把 npx @posthog/wizard@latest mcp add 作为快速安装路径。选择 Claude Code，按向导生成配置；如果它准备修改项目级文件，应先检查内容再接受。
所选身份应能访问目标项目，但不应拥有无关的管理员角色。如果浏览器里登录了多个 PostHog 账号，授权前要再次确认当前身份。
打开 Claude Code 的 MCP 视图，确认 PostHog 已连接，并在不调用变更操作的前提下列出工具。记录当前会话对项目、开关、实验、洞察等资源是只读还是可写。
在明确且较短的周期内读取一个已知事件或已保存洞察，并与 PostHog 界面核对项目、时区、筛选器、区间边界和结果。
| 检查点 | 通过证据 | 失败时 |
|---|---|---|
| 发现 | Claude Code 中显示 PostHog 已连接。 | 检查向导输出、客户端配置、重启状态和服务器地址。 |
| 身份 | 可见组织和项目与预期完全一致。 | 重新授权正确账号，并核对角色。 |
| 语义 | 已知查询的设置与结果和界面一致。 | 检查项目、事件名、属性、时区、筛选器和日期边界。 |
| 边界 | 只开放任务必需的工具和资源。 | 缩减账号角色、配置或工具范围。 |
从数据证据走到代码改动
最有效的流程不是先逛 Dashboard，而是先提出可证伪陈述：写清预期关系，以及什么证据会推翻它。随后让 Claude Code 分别检查埋点实现和 PostHog 数据，最后再把两边连接起来。这样可以避免“先猜代码问题，再按猜测查询”，也能防止一张噪声很大的图表直接驱动仓促改动。
| 阶段 | 关键问题 | Claude Code 任务 | 证据 |
|---|---|---|---|
| 界定 | 研究什么行为、用户、周期和决策？ | 写出假设、排除条件、基线和成功阈值。 | 分析约定。 |
| 检查代码 | 这个行为按设计应如何上报？ | 定位上报调用、属性构造、身份逻辑、开关和近期变更。 | 路径、代码行、提交和测试。 |
| 检查数据 | 实际观察到了什么？ | 查询足以检验假设的最小事件、漏斗、趋势、群组、开关或实验切片。 | 项目、查询、筛选、周期和结果。 |
| 对照 | 实现与行为在哪里偏离？ | 检查事件命名、属性缺失或变化、重复上报、身份归并和发布时间。 | 受证据支持的原因与备选解释。 |
| 改动 | 最小且可回退的修复是什么？ | 分别提出代码、数据结构、开关、迁移、测试、发布和回退方案。 | 补丁与验证计划。 |
| 复测 | 行为是否按预期变化？ | 在有效的改动后周期重新运行保存查询，并检查护栏指标。 | 可比较的前后记录。 |
可复用调查提示词：“在指定 PostHog 项目中，检验新用户激活是否在版本 X 发布后下降。使用项目时区，明确激活定义，排除内部用户，按平台拆分，并比较长度相同且已经结束的周期。检查仓库中的事件上报与身份代码，但不要修改文件或 PostHog 资源。返回查询定义、证据、局限、可能原因和最小验证方案。”
适合从哪里开始
- 埋点定义漂移：对照代码中的事件名和必填属性，检查近期实际数据结构与数量是否发生变化。
- 功能开关清理：先找出仓库中的开关引用，再核对发布比例、曝光、实验和活跃状态，之后才能删除代码。
- 漏斗转化下降：找到第一个明显变化的步骤，按用户群拆分，再结合版本发布或埋点变更分析，不要直接重写整套流程。
- 错误优先级：综合复现频率、受影响用户、路由、版本和堆栈证据，再结合本地实现提出修复。
同时保护隐私与分析可复现性
产品分析中可能包含用户标识、URL、文本属性、录屏、错误详情和组织元数据。Claude Code 只应读取当前问题必需的资源；汇总证据足够时，不要请求原始用户级数据；密钥或敏感载荷绝不能复制进提示词。只读应作为默认设置，但只读数据同样需要治理。
优先使用计数、分组趋势、漏斗和匿名群组。只有无法通过汇总数据完成诊断时，才请求单条事件。
保留项目 ID、时区、事件定义、筛选器、拆分维度、日期边界、采样和生成查询，不要只保存最终数字。
修改开关或实验可能直接影响线上用户。批准前应展示当前状态、目标状态、发布人群、护栏、负责人和回退方案。
涉及发布、回滚、定价、隐私或高影响产品决策时，应由责任人在 PostHog 界面再次确认。
两组数字不一致时，应系统对照：主机与项目、时区、日期边界是否含首尾、按事件还是按独立用户聚合、属性类型、测试账号过滤、身份合并逻辑、入库延迟、会话划分、采样和事件定义变化。在确认两条查询真正等价之前，不应贸然“修复”代码。
只有跨系统调查时再接入 QVeris
PostHog 产品分析仍应通过 PostHog MCP 这一直接供应商集成完成。实时检索 QVeris 目录后，没有发现准确的 PostHog Tool 或 Provider 页面，因此本页不会把无关结果塞进 CTA。只有调查确实需要另一个 API 或实时数据源时，才应先阅读 QVeris 文档，再到 QVeris演练场 独立测试该能力。
- 产品行为数据的来源继续以 PostHog 为准。
- 每个外部数据集都要标明供应商、时间、单位和连接假设。
- 把外部输出用于 PostHog 结论或写操作前，应先独立验证相应能力。
PostHog MCP 接入 Claude Code 常见问题
使用 PostHog 当前 MCP 文档与官方向导。原来的 PostHog/mcp 独立仓库在实现迁入主仓库后已经归档。
不会。MCP 服务于智能体流程；可视化探索、分享、权限核对和重大决策确认仍应使用 PostHog 界面。
应从只读开始。只有流程确实需要时才增加具体写能力，并在调用前核对准确目标与内容。
检查主机、项目、时区、日期边界、聚合方式、筛选器、身份模式、入库延迟、采样和事件定义漂移。
可以。它能把仓库引用与 PostHog 开关状态对照，但删除前仍要审查发布比例、曝光、实验状态、依赖和回退要求。
可以。依次追踪上报调用、条件判断、同意状态、身份、属性构造、网络、环境和发布时间，再用小范围 PostHog 查询核验。
参考资料与下一步
PostHog MCP 文档
PostHog 已归档 MCP 仓库
PostHog 产品分析
PostHog 功能开关
PostHog 隐私指南
Claude Code MCP 文档
QVeris 文档
QVeris演练场