How to Get Started with PostHog MCP Server

Ready to supercharge your data game with AI? The PostHog MCP Server lets you manage PostHog analytics—like creating annotations or querying user trends—using natural language in tools like Cline or Cursor. I got it up and running in only a few minutes, and it’s a total game-changer! In this tutorial, we’ll install the PostHog MCP Server on Cline in VS Code and Cursor, explore its killer features, and see why PostHog beats Google Analytics for open-source analytics. Let’s dive into the PostHog MCP Server magic!

💡

Want a great API Testing tool that generates beautiful API Documentation?

Want an integrated, All-in-One platform for your Developer Team to work together with maximum productivity?

Apidog delivers all your demands, and replaces Postman at a much more affordable price!

button

What is PostHog MCP Server?

The PostHog MCP Server is an open-source Model Context Protocol (MCP) server that connects AI assistants (like Cline or Cursor) to PostHog’s analytics platform via natural language commands. It enables tasks like creating annotations, managing projects, querying insights, and toggling feature flags—all without touching PostHog’s UI. Key features include:

Project Management: List and manage PostHog projects.
Annotations: Add timestamped notes for events (e.g., product launches).
Insights Queries: Analyze user behavior (e.g., sign-up trends).
Feature Flags: Control and query feature flags dynamically.
Error Tracking: Debug errors directly in your IDE.

It is a “must-have” for analytics automation, with 34+ GitHub stars showing community love. Ready to try it? Let’s go

Why Use PostHog MCP Server?

The PostHog MCP Server simplifies analytics workflows with AI-driven automation. Here’s why it rocks:

Natural Language: Manage analytics with simple commands.
Integration: Works with Claude Desktop, VS Code, Cursor, and more.
Open-Source (the best part): Free, customizable, and community-driven.
Privacy-First: Unlike Google Analytics, PostHog offers self-hosted options for full data control.

Compared to Google Analytics, PostHog shines with its open-source transparency, self-hosting flexibility, and all-in-one product suite (analytics, session replay, feature flags). Google Analytics often requires third-party integrations and lacks PostHog’s privacy focus, making the PostHog MCP Server a developer-friendly alternative for modern teams.

I used it to annotate a product launch in seconds—way faster than clicking through dashboards!

How to Install and Use PostHog MCP Server: Step-by-Step Guide

Let’s install the PostHog MCP Server on Cline in VS Code and Cursor, then test it with examples. You’ll need Python, a PostHog API key, and an IDE. No analytics guru status required—follow along!

1. Prerequisites

Python: 3.8+ (python3 --version).
uv: Python package manager (pip install uv).
VS Code/Cursor: Latest version with Cline extension.
PostHog API Key: Get one from app.posthog.com/settings (Personal API Key).
Docker: Optional for containerized setup (docker --version).
Disk Space: ~500MB for repo and dependencies.

2. Clone the PostHog MCP Repository

Open your terminal and clone the repo:

git clone https://github.com/PostHog/mcp.git
cd mcp

This pulls a ~5MB project. Took me a few seconds on Wi-Fi.

3. Install PostHog MCP Server with Cline in VS Code

Set Up Virtual Environment:

uv venv
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate  # Windows
uv pip install .

Configure API Key:
Create a .env file in the project root:

echo "PERSONAL_API_KEY=your-personal-api-key" > .env

Replace your-personal-api-key with your PostHog API key (which you can acquire from their official website).

Install Cline:
In VS Code, go to Extensions (Ctrl+Shift+X), install Cline, and open the Cline chat panel (Ctrl+Shift+P, “Cline: Open Chat”).

Add MCP Server:
Prompt Cline:

Install the PostHog MCP Server using uv and configure it with my API key.

Cline runs uv run posthog_mcp and updates ~/.aws/amazonq/mcp.json:

{
  "mcpServers": {
    "posthog": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp", "run", "posthog_mcp"],
      "env": {
        "PERSONAL_API_KEY": "your-personal-api-key"
      }
    }
  }
}

Replace /path/to/mcp with your repo path (e.g., /home/user/mcp).

The mcp server can also be found on cline's mcp marketplace. Simply head over there and search for "PostHog", then click install.

Cline will automaticaly perform the installation for you

Verify: Run /tools in Cline’s chat to list tools (e.g., create_annotation, list_projects). See the mcp servers icon in Cline? You’re set

4. Install PostHog MCP Server with Cursor

Clone and Install: Repeat Step 2’s clone and virtual environment setup.
Configure Cursor:
Open Cursor, go to Settings > Tools & Integrations > MCP Tools > Add a Custom MCP Server, and add the server config to .cursor/mcp.json:

{
  "mcpServers": {
    "posthog": {
      "command": "/path/to/uv",
      "args": ["--directory", "/path/to/mcp", "run", "posthog_mcp"],
      "env": {
        "PERSONAL_API_KEY": "your-personal-api-key"
      }
    }
  }
}

Find uv path with which uv (macOS/Linux) or where uv (Windows).

Restart Cursor: Click the refresh button in Settings > Tools & Integrations > MCP Tools.
Verify: Ask Cursor: “List available PostHog MCP Server tools.” It should show create_annotation, list_projects, etc.

5. Test PostHog MCP Server Features

Create an Annotation:
In Cline (VS Code) or Cursor, prompt:

Create a PostHog annotation in project 53497 for March 20th, 2025, with the description 'Launched new user onboarding flow' using the PostHog MCP Server.

The server calls PostHog’s API, adding the annotation. Check app.posthog.com to confirm.

Query Insights:
Prompt:

Show the trend of user sign-ups in project 98765 over the last 30 days using 
the PostHog MCP Server.

The server fetches structured data (e.g., JSON with sign-up trends). Example output:

{
  "insight": "user_signups",
  "project_id": 98765,
  "data": [
    {"date": "2025-06-01", "count": 120},
    {"date": "2025-06-02", "count": 135}
  ]
}

I ran this and got clean data in ~5 seconds—super slick

6. Containerized Setup (Optional)

For a Docker setup:

docker run -i --rm -e PERSONAL_API_KEY=your-personal-api-key ghcr.io/metorial/mcp-container--posthog--posthog-mcp--posthog-mcp posthog-mcp

Add to Cline/Cursor’s mcp.json:

{
  "mcpServers": {
    "posthog": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/metorial/mcp-container--posthog--posthog-mcp--posthog-mcp", "posthog-mcp"],
      "env": {
        "PERSONAL_API_KEY": "your-personal-api-key"
      }
    }
  }
}

Restart and verify as above. Docker’s cleanup (--rm) saved me disk space

7. Troubleshoot Common Issues

No Hammer Icon:
Check logs: ~/Library/Logs/Claude/mcp*.log (macOS) or %APPDATA%\Claude\logs (Windows).
Ensure absolute paths in mcp.json.
API Key Errors:
Verify key permissions in app.posthog.com/settings.
Use environment variables, not hardcoded keys.
Server Not Running:
Run uv run posthog_mcp manually to check errors.
Ensure Python 3.8+ and dependencies (uv pip install .).
Need Help? Check github.com/PostHog/mcp or X for tips.

Why PostHog Beats Google Analytics

PostHog’s PostHog MCP Server integrates with its platform, which outshines Google Analytics in:

Open-Source: Self-host for free, unlike Google Analytics’ proprietary lock-in.
Privacy: Control data with self-hosted instances; Google Analytics shares data with Google.
All-in-One: Analytics, session replay, feature flags, and experiments in one platform, versus Google’s fragmented tools.
Automation: PostHog MCP Server enables natural language queries, unlike Google Analytics’ manual dashboards.
Community: 1,500+ GitHub stars and active support, rivaling Google’s but with open-source flexibility.

I switched a side project to PostHog and loved the privacy and feature flag control—no Google Analytics bloat!

Customizing and Extending PostHog MCP Server

Level up your setup:

Custom Tools: Add new tools to the server (e.g., custom SQL insights) via github.com/PostHog/mcp.
Multiple Projects: Query all projects with “List all projects in my PostHog organization.”
Feature Flags: Generate code to toggle flags:

Generate a Python snippet to toggle feature flag 'new-ui' in project 12345
using the PostHog MCP Server.

Contribute: Submit PRs to enhance the server—PostHog welcomes them

Why PostHog MCP Server is a Dev Must-Have

The PostHog MCP Server makes analytics automation feel like chatting with a data guru. Its natural language interface and PostHog’s open-source edge beat Google Analytics for privacy-conscious teams. Setup can be finicky (API key woes!), but the PostHog docs and community are lifesavers.

Ready to rock the PostHog MCP Server? Fire up Cline or Cursor, query those insights, and share your analytics wins—I’m stoked to see your setup shine!

💡

button