MCP Posthog Server

MCP PostHog服务器（TypeScript）

一个内置于TypeScript中的模型上下文协议（MCP）服务器，它将PostHog操作作为工具公开。MCP客户端（例如，基于LLM的聊天代理）可以与他们的个人PostHog API密钥连接，以读取和写入用户的PostHog项目中的数据。

特性

• 通过MCP安全代理PostHog API呼叫
• 工具定义：

- 列出并创建队列 - *在此处添加更多已实施的工具*

• 错误处理和基本日志记录
• 已准备好使用Docker进行容器化

先决条件

• Node.js v16或更高版本
• npm
• PostHog项目ID、主机URL和个人API密钥。

- 在“项目设置”下查找您的项目ID。 - 查找您的主机URL（例如。， https://us.posthog.com, https://eu.posthog.com，或您的自托管URL）。 - 在账户设置->个人API密钥下生成个人API密钥。（复制整个密钥）。

• MCP TypeScript SDK(@modelcontextprotocol/sdk)

安装

# Clone the repo
git clone  mcp-posthog-server
cd mcp-posthog-server

# Install dependencies
npm install

# Build the TypeScript code
npm run build

配置

此服务器需要三个配置，可以通过命令行参数（仅限主机和密钥）或环境变量提供：

1. PostHog主持人： PostHog实例的基本URL（例如。， https://us.posthog.com).
2. PostHog个人API密钥： API访问的个人密钥。
3. PostHog项目ID： 项目的数字ID。

优先： 命令行参数（如果提供）覆盖Host和API键的环境变量。项目ID必须始终设置为环境变量。

环境变量：

创建一个 .env 在项目根目录中创建文件或在shell中设置这些变量：

# .env file example
POSTHOG_HOST=https://us.posthog.com
POSTHOG_API_KEY=YOUR_FULL_POSTHOG_PERSONAL_API_KEY
POSTHOG_PROJECT_ID=12345

命令行参数（覆盖Env中的主机/密钥）：

当直接与 node 或 npx，您可以将主机和API密钥作为参数传递：

node build/index.js  
# Requires POSTHOG_PROJECT_ID to be set in the environment

npx @your-org/mcp-posthog-server  
# Requires POSTHOG_PROJECT_ID to be set in the environment
# (Replace @your-org with your actual scope if publishing)

运行服务器

有几种方法可以运行服务器：

1.使用npm（构建后）：

# Make sure POSTHOG_HOST, POSTHOG_API_KEY, POSTHOG_PROJECT_ID are set in your env
npm start

2.直接使用Node（构建后）：

# Option A: Using Environment Variables
export POSTHOG_HOST=...
export POSTHOG_API_KEY=...
export POSTHOG_PROJECT_ID=...
node build/index.js

# Option B: Using Command-line Args (Host/Key) + Env Var (Project ID)
export POSTHOG_PROJECT_ID=...
node build/index.js https://us.posthog.com YOUR_FULL_POSTHOG_PERSONAL_API_KEY

3.使用npx（发布到npm后）：

替换 @your-org/mcp-posthog-server 使用实际发布的包名称。

export POSTHOG_PROJECT_ID=...
npx @your-org/mcp-posthog-server https://us.posthog.com YOUR_FULL_POSTHOG_PERSONAL_API_KEY

4.使用Docker（推荐部署）：

塑造形象：

docker build -t mcp-posthog-server .

运行容器。提供配置的主要方式有两种：

• 选项A：使用环境变量（通过 -e 旗帜）：

  docker run --rm -it \
    -e POSTHOG_HOST="https://us.posthog.com" \
    -e POSTHOG_API_KEY="YOUR_FULL_POSTHOG_PERSONAL_API_KEY" \
    -e POSTHOG_PROJECT_ID="12345" \
    mcp-posthog-server

• 选项B：安装 .env 文件（更便于本地使用）：

此方法直接从 .env 项目根目录中的文件。 确保该文件存在并包含 精确 变量名称： POSTHOG_HOST, POSTHOG_API_KEY, POSTHOG_PROJECT_ID.

  # Run this command from the project root directory
  docker run --rm -it \
    -v "$(pwd)/.env:/app/.env:ro" \
    mcp-posthog-server

由于此服务器默认使用stdio进行MCP通信，因此通常不需要映射端口(-p).您的MCP客户端将通过执行相应的 docker run 命令（选项A或B，取决于您在配置客户端时处理机密的方式）。

项目结构

.
├── src/
│   ├── index.ts            # Server entry point, MCP setup, tool registration
│   ├── posthog-client.ts   # PostHog client/config initialization helper
│   └── tools/
│       └── cohorts.ts      # Cohort tool schemas and handlers
├── Dockerfile              # For building production container image
├── Readme.md               # This file
├── package.json
├── package-lock.json
├── tsconfig.json
└── .env.example            # Example environment variables (optional)

连接您的MCP兼容客户端

配置您的客户端（例如Cursor、Claude Desktop）以运行服务器。确切的命令取决于您选择如何运行它（Node、npx、Docker）。

光标示例(.cursor/mcp.json)使用Docker：

{
  "mcpServers": {
    "posthog": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "POSTHOG_HOST=https://us.posthog.com",
        "-e", "POSTHOG_API_KEY=YOUR_FULL_POSTHOG_PERSONAL_API_KEY",
        "-e", "POSTHOG_PROJECT_ID=12345",
        "mcp-posthog-server"
      ]
    }
  }
}

光标示例(.cursor/mcp.json 或 ~/.cursor/mcp.json)使用节点：

此配置告诉Cursor如何使用Node直接运行构建的服务器。 确保 args 路径指向正确的绝对位置 build/index.js 在您的系统上。

{
  "mcpServers": {
    "posthog": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-posthog-server/build/index.js"
      ],
      "env": {
          "POSTHOG_HOST": "https://us.posthog.com",
          "POSTHOG_API_KEY": "YOUR_FULL_POSTHOG_PERSONAL_API_KEY",
          "POSTHOG_PROJECT_ID": "12345"
      }
    }
  }
}

配置Cursor（您可能需要重新加载窗口）并确保服务器可以运行（通过Docker或设置了正确环境变量的Node）后，您可以使用您定义的密钥调用工具（例如。， @posthog):

@posthog list cohorts

@posthog create cohort named "High Value Users" with criteria email contains "@company.com"

使用自定义工具进行扩展

1. 在下创建新文件 src/tools/ （例如。， src/tools/featureFlags.ts).
2. 为工具的输入定义Zod模式。
3. 定义并导出工具逻辑的异步处理函数（例如。， export async function getFeatureFlagHandler(args: GetFlagInput)).

- 使用 posthogApiFetch 助手或直接API调用。 - 返回结果 { content: [{ type: "text", text: ... }] } 格式。

1. 将架构和处理程序导入 src/index.ts.
2. 使用注册工具 server.tool(name, description, schema.shape, handler);.
3. 重建服务器(npm run build).

贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/my-tool)
3. 提交您的更改(git commit -m "feat: add my custom tool")
4. 推到分支(git push origin feature/my-tool)
5. 打开拉取请求

许可证

MIT许可证