PostHog

PostHog MCP

PostHog 官方 MCP 服务。PostHog 让你的产品实现自驱：它会读取你的数据，并与你一起发布变更，而不会擅自行动。此服务为 MCP 客户端（Claude、Cursor、VS Code、Zed 等）提供完整功能：分析和 SQL、仪表板、实验、功能标记、问卷、会话回放、错误跟踪等。

文档：https://posthog.com/docs/model-context-protocol

使用 MCP 服务

快速安装

运行以下命令，即可将 MCP 服务自动安装到 Cursor、Claude、Claude Code、VS Code 和 Zed：

npx @posthog/wizard@latest mcp add

手动安装

1. 使用 MCP Server preset 获取个人 API 密钥。

2. 将 MCP 配置添加到桌面客户端（例如 Cursor、Windsurf、Claude Desktop），并添加个人 API 密钥

{
  "mcpServers": {
    "posthog": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.posthog.com/mcp",
        "--header",
        "Authorization:${POSTHOG_AUTH_HEADER}"
      ],
      "env": {
        "POSTHOG_AUTH_HEADER": "Bearer {INSERT_YOUR_PERSONAL_API_KEY_HERE}"
      }
    }
  }
}

最简 Node 客户端（Streamable HTTP）

如果你想从 Node 调用 MCP（在 IDE 之外），请使用 Model Context Protocol SDK 的 Streamable HTTP 传输方式。

• 身份验证： 使用 PostHog 个人 API 密钥，并将其作为 Bearer 令牌传入 Authorization。
• Accept 标头： 客户端必须包含 Accept: application/json, text/event-stream。
• 生命周期： MCP 要求先执行 initialize，然后由客户端发送 notifications/initialized；SDK 会在 connect() 期间完成此操作。

// tools-list.mjs
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
import { ListToolsResultSchema } from '@modelcontextprotocol/sdk/types.js'
import { mkdirSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import { URL } from 'node:url'

const AUTH = process.env.POSTHOG_AUTH_HEADER // "Bearer phx_…"
const MCP_URL = process.env.MCP_URL || 'https://mcp.posthog.com/mcp'

if (!AUTH?.startsWith('Bearer ')) {
  console.error('Set POSTHOG_AUTH_HEADER="Bearer phx_..."')
  process.exit(1)
}

const transport = new StreamableHTTPClientTransport(new URL(MCP_URL), {
  requestInit: {
    headers: {
      Authorization: AUTH,
      // Required for Streamable HTTP (JSON + SSE)
      Accept: 'application/json, text/event-stream',
    },
  },
  serverInfo: { name: 'example-node-client', version: '0.0.1' },
})

const client = new Client({ name: 'example-node-client', version: '0.0.1' })

// Handles initialize + notifications/initialized
await client.connect(transport)

const toolsResp = await client.request({ method: 'tools/list' }, ListToolsResultSchema) // { tools: [...] }
const tools = toolsResp?.tools ?? []
console.log('Tools:', tools.length)

// (Optional) Save the full JSON-RPC envelope to a file (run from repo root)
const envelope = { jsonrpc: '2.0', id: 'list-1', result: toolsResp }
mkdirSync('reports', { recursive: true })
writeFileSync(join('reports', 'tools-list-http.json'), JSON.stringify(envelope, null, 2))
console.log('Saved: reports/tools-list-http.json')

await client.close()

为什么需要这些标头和步骤？

• Streamable HTTP 要求 Accept 标头同时包含 JSON 和 SSE。
• 执行 initialize 后，客户端必须发送 notifications/initialized；SDK 会在 connect() 中为你完成此操作。

另请参阅 PostHog MCP 主文档，了解可用工具和设置流程：https://posthog.com/docs/model-context-protocol

提示词示例

以下是展示真实提示词和预期输出的详细示例：

示例 1：功能标记管理

提示词：“创建一个名为 'new-checkout-flow' 的功能标记，为 20% 的用户启用，并向我展示配置”

执行过程：

1. create-feature-flag 工具创建功能标记，并设置 20% 的发布比例
2. 返回功能标记配置，包括键、发布比例和目标规则

预期输出：

Created feature flag 'new-checkout-flow':
- Key: new-checkout-flow
- Active: true
- Rollout: 20% of all users
- URL: https://us.posthog.com/project/<project-id>/feature_flags/12345

示例 2：分析查询

提示词：“过去 7 天内有多少独立用户注册了？按天细分。”

执行过程：

1. query-trends 工具执行趋势查询，并筛选 $signup 事件
2. 返回按天统计的数量，并按独立用户聚合

预期输出：

Signups over the last 7 days:

| Date       | Unique users |
|------------|--------------|
| 2025-01-17 | 142          |
| 2025-01-18 | 156          |
| 2025-01-19 | 98           |
| ...        | ...          |

Total: 847 unique signups

示例 3：创建并监控 A/B 测试

提示词：“为我们的定价页面创建一个 A/B 测试，用于衡量转化到结账页面的情况”

执行过程：

1. experiment-create 工具创建实验，并设置对照组和测试组
2. 设置漏斗指标：查看定价页面 → 查看结账页面
3. 创建关联的功能标记，用于分配变体

预期输出：

Created experiment 'Pricing page test':
- Feature flag: pricing-page-test
- Variants: control (50%), test (50%)
- Primary metric: Funnel conversion (pricing_page → checkout)
- Status: Draft (ready to launch)
- URL: https://us.posthog.com/project/<project-id>/experiments/789

示例 4：错误调查

提示词：“本周我的项目中最常见的 5 个错误是什么？分别影响了多少用户？”

执行过程：

1. query-error-tracking-issues-list 工具获取按发生次数排序的错误组
2. 返回错误详情，包括受影响用户数

预期输出：

Top 5 errors this week:

1. TypeError: Cannot read property 'id' of undefined
   - Occurrences: 1,247
   - Users affected: 89
   - First seen: 2 days ago

2. NetworkError: Failed to fetch
   - Occurrences: 856
   - Users affected: 234
   - First seen: 5 days ago
...

快速提示词

对于简单查询，你可以使用更简短的提示词：

• “我有哪些启用的功能标记？”
• “显示我本周的大模型成本”
• “列出我的仪表板”
• “正在跟踪哪些事件？”

功能筛选

你可以在 MCP URL 中添加查询参数，以限制可用工具。如果未指定功能，则所有工具均可用。指定功能后，只会公开与这些功能匹配的工具。

https://mcp.posthog.com/mcp?features=flags,workspace,dashboards

可用功能：

Feature	描述
actions	操作
alerts	警报
annotations	注释
batch_exports	数据管道
business_knowledge	商业知识
canvas	画布
cohorts	群组
conversations	对话
core	核心实用工具（项目切换、文档搜索）
customer_analytics	客户分析
dashboards	仪表板
data_catalog	数据目录
data_schema	数据架构探索
data_warehouse	数据仓库
debug	调试和诊断工具
docs	PostHog 文档搜索
early_access_features	抢先体验功能
endpoints	端点
engineering_analytics	工程分析
error_tracking	错误跟踪警报
events	事件和属性定义
experiments	实验
feedback	向 PostHog 团队发送反馈
field_notes	实地笔记
flags	功能标志
health_issues	健康状况
hog_function_templates	CDP 函数模板浏览
hog_functions	函数
insights	洞察与分析
integrations	集成
links	PostHog 应用 URL 生成
llm_analytics	AI 可观测性
logs	日志
managed_migrations	托管迁移
marketing_analytics	营销分析
messaging	消息
mcp_analytics	MCP 分析
mcp_store	MCP Store
metrics	指标
notebooks	笔记本
persons	人员
platform_features	平台功能
product_analytics	产品分析
reminders	提醒
replay	会话回放
replay_vision	回放视觉
reverse_proxy	反向代理记录管理
review_hog	ReviewHog
signals	信号
skills	技能
sql	SQL 查询执行
stamphog	Stamphog
streamlit_apps	Streamlit 应用
subscriptions	订阅
surveys	调查
tasks	任务
tracing	追踪
visual_review	视觉审查
warehouse_sources	仓库数据源
web_analytics	Web 分析
workflows	工作流
workspace	组织和项目管理

**注意：**在功能名称中，连字符和下划线视为等价（例如，error-tracking 和 error_tracking 都可用）。

如需查看各项功能可用的工具，请参阅我们的文档，或查看 schema/tool-definitions-all.json。

cli 模式下的学习与技能

Claude 网页版和桌面版会在序列化后的 inputSchema 达到 16,384 个字符时，静默丢弃 exec。 在 cli 模式下，exec 工具会在其架构中保留日常调用所需的指导。 精简的工具域索引会保留在 command 架构中，以便 Claude 在调用前发现相关工具。 可选的、特定任务的指导通过同一工具提供：

• learn 列出可用的内置指南，以及启用后 PostHog/项目技能的发现语法。
• learn analytics 加载详细的分析指导和示例。
• learn visualizations 在可视化功能可用时加载渲染指导。
• learn urls 加载 PostHog 应用链接格式规则（对其他客户端而言，该规则保留在架构中；对 Claude 网页版和桌面版而言，则作为指南提供，以控制架构的字符数）。
• learn feedback 在反馈功能可用时加载反馈指导。
• learn skills 列出已发布的 PostHog 包（posthog:）和当前项目的 Skills 存储库（project:）中的限定名称。
• learn -s "<最多 8 个关键词>" 在这两个来源的名称、描述、Markdown 正文和捆绑文件路径中进行搜索。如果查询包含超过 8 个关键词，则优先使用较长的关键词。两个来源的结果会合并为一个相关性排序列表。
• learn -d <source>:<skill> [...] 输出每项指定技能的单行描述，而不读取其正文（每次调用最多 20 项）。未知名称会在行内报告，不会导致批次失败。
• learn posthog:<skill> [path] 或 learn project:<skill> [path] 读取某项技能或其捆绑文件之一。
• learn <source>:<skill> <path> [path...] 可在一次调用中读取多个捆绑文件；learn <source>:<skill> [<source>:<skill>...] 可在一次调用中读取多项技能（最多 10 个目标）。
• learn <source>:<skill> <path> -s "<最多 8 个关键词>" 在一个 Markdown 文件中进行搜索。
• learn <source>:<skill> <path> --lines <start>:<end> 读取包含起止行的行范围。

内置指南仅适用于 Claude 网页版和桌面版。启用 mcp-exec-skills 功能标志后，所有 cli 模式客户端均可独立使用技能发现功能。其他客户端（包括 Claude Code）只能使用技能命令，不会收到 Claude 的内置指南。如果该标志缺失、已禁用或无法评估，则技能命令不会加入架构，并且在运行时会被拒绝。 启用技能发现后，内联提示词会告知每个非插件 cli 客户端（包括 Claude 网页版和桌面版）在处理非简单的 PostHog 工作前，先使用 learn -s "<任务关键词>" 搜索，使用完全匹配的限定名称加载匹配项，并在选择工具前遵循已加载的 SKILL.md。简单查询和无关对话可跳过此工作流。 技能使用仅供参考：即使跳过 learn，产品 call 也不会被拒绝，因此无论客户端是否持有 MCP 会话 ID，行为都相同。 技能包通过 Redis 共享：每个 Pod 在启动时加载一次，将其解析到内存中，并使用解析后的目录处理每个 learn 命令。 后台定时器会轮询 Redis 中的一个小型版本键；只有版本发生变化时，Pod 才会重新读取归档字节。 当共享副本超过十分钟时，每次由一个 Pod 从源站刷新归档，并使用条件请求，使未更改的版本返回 304。 缓存字节会保留三十天，并在每次刷新时延长保留期限，因此源站中断时仍可提供上次成功获取的归档。 learn、initialize 或 discover 请求都不会从 Redis 读取归档。 默认情况下，归档从 https://github.com/PostHog/posthog/releases/download/agent-skills-latest/skills.zip 加载。 本地开发时，可设置 POSTHOG_MCP_SKILLS_URL 使用其他归档。 自定义归档 URL 使用独立的 Redis 缓存命名空间，因此本地技能包无法读取或覆盖已发布技能包的缓存条目。 项目技能直接从经过请求身份验证的项目读取，不由 MCP 服务缓存。 learn 只公开最新、启用且未分类的技能；scouts 等特定类别的技能保留在各自的入口中。 项目全文搜索最多检索 10 个技能，每个技能提供两段简短片段，数据库超时时间为五秒。 单个 learn 响应不超过 44,000 个字符；较大的参考资料会返回标题大纲，供后续搜索或按行读取。 固定的命令语法保留在工具架构中，技能名称和正文则仅在请求时加载。 无论功能标志如何，consumer=plugin 和 consumer=posthog-code 都会省略 learn，因为这两个入口已经提供了各自打包的技能上下文。

其他客户端仍保留完整的内联命令参考。

工具筛选

在 CLI 模式下，tools 和 exclude_tools 也适用于带命名空间的已连接工具。features 筛选器会排除已连接的工具，除非 tools 明确列出这些工具。排除项优先于显式选择项。

如需更精细的控制，可以使用 tools 查询参数按名称将特定工具加入允许列表。无论工具所属的功能类别是什么，只有列出的确切工具名称会被公开。

https://mcp.posthog.com/mcp?tools=dashboard-get,feature-flag-get-all,execute-sql

同时提供 features 和 tools 时，两者按并集组合——匹配某个功能类别或出现在工具列表中的工具都会被纳入。这样，你可以选择一组功能，并在此基础上添加少量单独的工具：

https://mcp.posthog.com/mcp?features=flags&tools=dashboard-get

上面的示例会公开所有 flag 工具以及 dashboard-get。

服务模式（工具与 CLI）

MCP 服务可以逐个注册所有 PostHog 工具（tools 模式），也可以将它们封装在一个类似 CLI 的 exec 工具后面（cli 模式）。 所有客户端默认使用 cli 模式。 如果调用方未固定模式，服务仅会为少数更适合使用完整逐工具列表的客户端自动选择 tools 模式，目前包括 Cursor（根据其自报的客户端名称或 Cursor/… User-Agent 匹配）。 所有 OpenAI 平台（ChatGPT、Codex、Agent Builder、Responses API）均使用 cli 默认模式。OpenAI 的 openai-mcp 客户端会缓存其为已发布插件获取的工具列表，并向插件的所有用户提供该快照，因此，插件列表应使用的模式由提交给 OpenAI 的 URL 固定，而不是根据 User-Agent 标签推断。

你可以使用查询参数或标头自行固定选择。仅接受 tools 和 cli：

https://mcp.posthog.com/mcp?mode=cli
https://mcp.posthog.com/mcp?mode=tools

x-posthog-mcp-mode: cli
x-posthog-mcp-mode: tools

值	行为
tools	强制使用 tools 模式（每个 PostHog 工具对应一个 MCP 工具）。
cli	强制使用 cli 模式（单个 exec 工具封装所有工具）。

同时设置标头和查询参数时，以标头为准。 显式设置的值始终优先于客户端自动检测；其他任何值都会被忽略，并改用自动检测结果。

cli 模式的命令界面已在 posthog.com/docs/model-context-protocol/tools 上公开文档化，该页面会在构建时嵌入 schema/exec-command-reference.md。 此片段由 scripts/generate-exec-docs.ts 根据 src/templates/sections/ 中的模板生成（属于 hogli build:openapi 的一部分）；请编辑模板，而不是该片段。

使用方归因

安装或代理 PostHog MCP 的封装应用和 AI 工具插件可以自行标识，以便将使用情况归因到安装路径（例如，通过插件安装还是手动粘贴 URL）。封装的 MCP 客户端（Claude Code、Cursor，……）已通过 MCP clientInfo 握手单独记录；此信号仅用于标识封装环境。

https://mcp.posthog.com/mcp?consumer=plugin

x-posthog-mcp-consumer: plugin

同时设置标头和查询参数时，以标头为准。保留值：plugin（AI 工具插件安装）、posthog-code（PostHog Desktop Tasks 沙盒）、slack（Slack 集成）。

数据处理

MCP 服务运行在 PostHog 的美国和欧盟 Kubernetes 集群中，并将会话状态存储在你所连接的区域。 前置的无状态 Cloudflare Worker 仅负责验证请求并将请求路由到你的云区域；它不会存储任何敏感数据。

使用可自托管实例

如果你使用的是 PostHog 可自托管实例，可以在本地或自己的基础设施上运行 MCP 服务时设置 POSTHOG_API_BASE_URL 环境变量，以指定自定义基础 URL，例如 POSTHOG_API_BASE_URL=https://posthog.example.com

开发

要在本地运行 MCP 服务（基于 Node 的 Hono），请运行以下命令：

pnpm run dev

或者在仓库根目录使用 bin/start-mcp-server，它还会初始化 .env 并设置 Redis 和端口默认值。 然后在 MCP 配置中将 https://mcp.posthog.com/mcp 替换为 http://localhost:8787/mcp。

服务默认使用端口 8787，从 .env 读取配置（参见 .env.example），并要求本地 Redis 使用端口 6379 来保存会话状态；生产部署必须将 REDIS_URL 设置为 TLS 加密的 rediss:// 端点。

启动时会等待 Redis 就绪，最长 45 秒，期间会重试连接。如果 Redis 停止接受重连或等待超时，进程将退出，不会启动 HTTP 服务。

会话缓存

每个 MCP 传输会话都会保留自己的当前组织和项目，包括未固定 project_id 或 organization_id 的连接。未固定的会话会从用户当前的组织和项目开始，但须处于凭据允许的范围内。之后在网站上进行的更改，以及其他 MCP 会话中的切换，都不会改变此选择。switch-project 和 switch-organization 只会更新发起调用的会话；切换到其他组织时，会清除之前的项目。

switch-project 需要一个正整数 projectId。也接受 project_id 和 new_project_id 作为别名。如果提供了多个参数，优先使用 projectId，其次是 project_id。

没有 MCP 会话 ID 的客户端改用 SDK 的 conversation_id。后续调用时，请传回首次工具调用返回的句柄。若切换操作没有携带会话或对话句柄，则会返回错误和一个新句柄；请使用该句柄重试以应用切换。对话状态与凭据绑定，并与传输会话分开存储。没有携带任一身份标识的调用会从连接固定的选择或默认选择开始。如果客户端无法保留对话句柄，请在连接 URL 中固定项目或组织。

旧版 JSON-RPC 批量请求会分别还原每次调用的对话句柄。封装器的 sessionId 查询参数只是分析提示，不能替代对话句柄；仅通过封装器发起的调用仍会从 SDK 获取一个新句柄。

会话默认值只存储一次，并与显式选择分开存储。延迟执行的查找可以为自身请求解析上下文，而不会覆盖已完成的切换。

如果默认项目发现失败，后续请求会在会话最初的组织内重试。首次成功发现的项目会被采用，显式切换仍具有优先权。切换组织时，如果目标组织的团队列表确认所选项目属于该组织，即使凭据无法读取项目元数据，也会保留该项目。

会话的客户端上下文存储在一个 mcp:s:<id>:c 键中，空闲 24 小时后过期；会话中的每个请求都会刷新过期时间。 并发请求会通过 Lua 比较并合并各自的字段，因此会话中途首次出现的字段不会因重叠写入而丢失。

监控 mcp_session_cache_operations_total 中的 read_error 和 write_error。 两者都不会阻塞请求：读取失败时，会使用当前请求携带的上下文，因此归属信息会降级，而不是导致调用失败。 两者还会记录以 [McpSessionRedisStore] 开头的警告，因此可在日志中检索此路径上的 Redis 故障，而不必只查看指标计数器。

边缘代理 Worker（Cloudflare）

在生产环境中，一个轻量级 Cloudflare Worker 位于 Hono 部署前端，作为无状态边缘路由器：它提供 OAuth 元数据端点、验证令牌、解析调用方的云区域，并将 /mcp 流量代理到 mcp.us.posthog.com / mcp.eu.posthog.com。 它本身不提供 MCP 协议服务——请参阅 ARCHITECTURE.md。 若只想在本地运行 Worker：

pnpm run dev:proxy

使用本地资源进行开发

要为 MCP 资源（工作流、提示词、示例）启用热加载进行开发：

1. 启动 context-mill 开发服务器：cd ../context-mill && npm run dev
2. 使用本地资源启动 MCP 服务：pnpm run dev:local-resources（使用指向 context-mill 的 POSTHOG_MCP_LOCAL_SKILLS_URL 运行 bin/start-mcp-server）

示例仓库中的更改会在下次请求时生效。

项目结构

• src/ - MCP 服务：Hono 应用（src/hono/）、工具处理程序（src/tools/）、提示词模板（src/templates/）
• definitions/ - 手工编写的 YAML 工具定义（按产品划分的 YAML 位于 monorepo 中的 products/<product>/mcp/）
• schema/ - 生成的架构文件，包括 tool-definitions-all.json（完整工具目录）

开发命令

• pnpm run dev - 启动 MCP 开发服务器
• pnpm run dev:proxy - 启动 edge-proxy worker（wrangler）
• pnpm run lint / pnpm run format:check - 检查 lint 和格式，不修改文件
• pnpm run lint:fix - 应用安全的 lint 修复，不应用建议性修复
• pnpm run format - 仅使用 Oxfmt 格式化代码
• pnpm run fix - 应用安全的 lint 修复，始终格式化代码，并报告任一工具的失败

添加新工具

大多数工具由 products/<product>/mcp/tools.yaml 生成。 按照实现 MCP 工具技能和手册指南完成此流程。 仅对手写工具使用 src/tools/README.md。

环境变量

将根目录下的 .env.example 复制为 .env，并根据需要调整值。

配置 Model Context Protocol Inspector

开发期间，你可以使用 MCP Inspector 直接检查 MCP 工具调用结果。

你可以使用以下命令运行它：

npx @modelcontextprotocol/inspector npx -y mcp-remote@latest http://localhost:8787/mcp --header "\"Authorization: Bearer {INSERT_YOUR_PERSONAL_API_KEY_HERE}\""

或者，你也可以在 MCP Inspector 中使用以下配置：

使用 STDIO 传输类型。

命令：

npx

参数：

-y mcp-remote@latest http://localhost:8787/mcp --header "Authorization: Bearer {INSERT_YOUR_PERSONAL_API_KEY_HERE}"

使用 Claude Desktop 进行开发

Claude Desktop 是测试 MCP Apps 最简单的方式之一，而 PostHog Desktop 不支持 MCP Apps。你可以在 Settings > Developer 中配置访问权限，然后使用以下内容编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "posthog-local": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "http://localhost:8787/mcp"]
    }
  }
}

隐私与支持

• 隐私政策： https://posthog.com/privacy
• 服务条款： https://posthog.com/terms
• 支持： https://posthog.com/questions 或发送邮件至 [email protected]
• GitHub 问题： https://github.com/PostHog/posthog/issues

数据处理

MCP 服务充当访问你的 PostHog 实例的代理。它不会存储你的分析数据——所有查询都针对你的 PostHog 项目执行，结果会直接返回给你的 AI 客户端。会话状态（当前项目/组织）会以你的 API 密钥哈希为键进行临时缓存。

欧盟用户请使用 mcp-eu.posthog.com 端点，确保 OAuth 流程路由至欧盟 PostHog 实例。