Posthog MCP

🚀 PostHog MCP Server 📊

A Model Context Protocol (MCP) server that interacts with PostHog. Create annotations and manage projects directly from Claude Desktop!

✨ Features

• List Projects: View all available PostHog projects in your organization.
• Create Annotations: Add annotations to PostHog projects, optionally with timestamps. [This list can be longer, basically all features provided by our API...]

📦 Installation

Prerequisites

• Python 3.10 or higher.
• The uv package manager.
• Obtain a PostHog API key with annotation:write and project:read permissions in your Project Settings.

Installation Steps

# Clone the repository
git clone git@github.com:PostHog/posthog-mcp.git

# Or use HTTPS: git clone https://github.com/PostHog/posthog-mcp.git

cd posthog-mcp

uv venv
source .venv/bin/activate

# Install dependencies
uv pip install .

Configuration

• Create a .env file in the project root directory:

PERSONAL_API_KEY=phx_your_posthog_api_key_here

Claude Desktop Setup

• Install Claude Desktop.
• Open Claude Desktop settings and click "Edit Configuration". Alternatively, you can directly open the file:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
• Add the following content to your claude_desktop_config.json (adjust the path according to your system):

{
  "mcpServers": {
    "posthog": {
      "command": "/path/to/uv",  # Run this command to get: which uv
      "args": [
        "--directory",
        "/path/to/your/posthog-mcp",  # The full path of this project
        "run",
        "posthog_mcp"
      ]
    }
  }
}

Refer to the latest documentation if you encounter issues setting up Claude Desktop as an MCP client.

💻 Usage Examples

Basic Usage

After installation, you'll see a hammer 🔨 icon in Claude Desktop. The following commands are available:

List Projects

Ask Claude:

"List my PostHog projects"

Get and Search Insights

Ask Claude: "List my PostHog insights" or "Search for revenue insights in PostHog"

Online Document Search

You can ask:

• "How to use reverse proxy in Next.js with PostHog?"

Create Annotations

Using the project ID obtained from the project list, ask Claude:

"Create a PostHog annotation in project 53497 with the content 'Deployed v1.2.3'"

Or specify a specific date:

"Create a PostHog annotation in project 53497 for March 20th with the content 'Launched a new marketing campaign'"

🔍 Troubleshooting

• If the hammer icon doesn't appear, restart Claude Desktop.
• Check the log path: ~/Library/Logs/Claude/mcp*.log (macOS) or %APPDATA%\Claude\logs (Windows).
• Ensure that the API key has the correct permissions.

💡 Usage Tip

Make sure to set the environment variables correctly and check your network connection before use.