Posthog

🚀 PostHog MCP Server 📊

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

🚀 Quick Start

The PostHog MCP Server enables seamless interaction with PostHog. After installation, you can use Claude Desktop to perform various operations on PostHog projects.

✨ Features

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

📦 Installation

Prerequisites

• Python 3.10 or higher.
• The uv package manager.
• A PostHog API Key with annotation:write and project:read permissions, which can be obtained from 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 open the file via the following paths:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
• Add the following to your claude_desktop_config.json (adjust the paths according to your system):

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

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

💻 Usage Examples

Basic Usage

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

List Projects

Ask Claude to execute:

"List my PostHog projects"

Get and Search Insights

Ask Claude to execute:

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

Online Documentation Search

You can ask questions like:

"How to set up a reverse proxy for PostHog in Nextjs?"

Create Annotations

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

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

Or specify a date:

"Create a PostHog annotation in project 53497 on 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 your PostHog API Key has the correct permissions.
• Ensure all paths in claude_desktop_config.json are absolute paths.

🤝 Contributing

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