posthog mcp

Local 2025-08-31 23:22:42 0
Monitoring @PostHog/posthog-mcp

A Model Context Protocol server that enables Claude Desktop users to interact directly with PostHog, allowing them to view projects and create annotations through natural language commands.

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 ?️

  1. Prerequisites

  2. Python 3.10 or higher

  3. uv package manager

  4. PostHog API Key with annotation:write and project:read scopes obtained from your project settings

  5. Installation

# clone the repo
git clone [email protected]: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 .

  1. Configuration

  2. Create a .env file in the project root: 

    PERSONAL_API_KEY=phx_your_posthog_api_key_here

  3. Claude Desktop Setup

  4. Install Claude Desktop
  5. 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%Claudeclaude_desktop_config.json
  6. 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%Claudelogs (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.

[
  {
    "description": "List all available PostHog projects.",
    "inputSchema": {
      "properties": {},
      "title": "list_posthog_projectsArguments",
      "type": "object"
    },
    "name": "list_posthog_projects"
  },
  {
    "description": "Create a PostHog annotation.nnArgs:n    project_id: The ID of the project as an integer (e.g. 99423)n    content: The content/text of the annotationn    date_marker: Optional ISO-8601 timestamp for the annotation (e.g. 2024-03-20T14:15:22Z)n",
    "inputSchema": {
      "properties": {
        "content": {
          "title": "Content",
          "type": "string"
        },
        "date_marker": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": {
            "path": "uv.lock",
            "type": "blob"
          },
          "title": "Date Marker"
        },
        "project_id": {
          "title": "Project Id",
          "type": "integer"
        }
      },
      "required": [
        "project_id",
        "content"
      ],
      "title": "create_posthog_annotationArguments",
      "type": "object"
    },
    "name": "create_posthog_annotation"
  }
]