PostHog MCP Server 📊

A Model Context Protocol (MCP) server for interacting with PostHog. Create annotations and manage projects directly through Claude Desktop!

Features 🚀

List Projects: View all available PostHog projects in your organization
Create Annotations: Add annotations to your PostHog projects with optional timestamps [this list can be much longer, anything our api has basically...]

Setup 🛠️

Prerequisites
- Python 3.10 or higher
- uv package manager
- PostHog API Key with annotation:write and project:read scopes obtained from your project settings

Installation

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

# or if https, use: 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:
```
PERSONAL_API_KEY=phx_your_posthog_api_key_here
```
Claude Desktop Setup
- Install Claude Desktop
- Open Claude Desktop settings and click "Edit Config". Alternatively, you can open the file from:
  - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  - Windows: %APPDATA%\Claude\claude_desktop_config.json
- Add this to your claude_desktop_config.json (adjust paths according to your system):
```
{
  "mcpServers": {
    "posthog": {
      "command": "/path/to/uv",  # Get this by running: which uv
      "args": [
        "--directory",
        "/path/to/your/posthog-mcp",  # Full path to this project
        "run",
        "posthog_mcp"
      ]
    }
  }
}
```
  Check the latest documentation on setting up Claude Desktop as MCP client if you ran into any issues.

Usage 💡

After setup, 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 for Insights

Ask Claude:

"List my PostHog insights" or "Search for revenue insights in my PostHog"

Search for documentations online

You can ask:

"how can i do reverse proxy in nextjs in posthog?"

Create Annotation

Using the Project ID you get from the list of projects, ask Claude:

"Create a PostHog annotation in project 53497 saying 'Deployed v1.2.3'"

or with a specific date:

"Create a PostHog annotation in project 53497 for March 20th saying 'Started new marketing campaign'"

Troubleshooting 🔍

If the hammer icon doesn't appear, restart Claude Desktop
Check logs at ~/Library/Logs/Claude/mcp*.log (macOS) or %APPDATA%\Claude\logs (Windows)
Verify your PostHog API key has the correct permissions
Make sure all paths in claude_desktop_config.json are absolute paths

Contributing 🤝

Feel free to open issues and PRs! We follow PostHog's contribution guidelines.