How to Use the PostHog MCP Server?

PostHog MCP server stands out as a robust tool for integrating PostHog’s powerful analytics platform with AI-enhanced environments like Claude Desktop or Cursor. The Model Context Protocol (MCP) server empowers developers to interact with PostHog’s features—such as project management, annotation creation, feature flag queries, and error analysis—using natural language commands. This seamless integration reduces manual effort, minimizes errors, and accelerates workflows, making it an essential tool for developers and data teams alike.

💡

To enhance your API interactions during this setup, we recommend Apidog, a free API testing tool that simplifies working with PostHog’s endpoints. Download Apidog for free to streamline your experience with the PostHog MCP server.

button

Understanding the PostHog MCP Server

The PostHog MCP server is a specialized server that leverages the Model Context Protocol to bridge PostHog’s analytics capabilities with AI-powered tools. It enables developers to perform complex tasks—like listing projects, creating timestamped annotations, querying feature flags, or analyzing errors—through intuitive natural language inputs within supported desktop clients. By automating these interactions, the server eliminates repetitive manual tasks and ensures data accuracy.

Furthermore, the PostHog MCP server operates as a local or containerized service, piping PostHog data directly into AI agent sessions. This integration allows for real-time analytics management without leaving your development environment, enhancing productivity and decision-making. For instance, instead of navigating PostHog’s UI to check feature flags, you can query them directly in your AI tool, receiving structured responses instantly.

Next, let’s prepare the prerequisites for setting up the server.

Prerequisites for Using the PostHog MCP Server

Before configuring the PostHog MCP server, ensure you have the following tools and resources:

PostHog Account: Create an account at posthog and generate a personal API key from the settings panel.
Supported Desktop Client: Install Claude Desktop, Cursor, or Windsurf to interact with the MCP server.
Python Environment: Use Python 3.8 or higher, along with a dependency manager like uv (install via pip install uv).
Git: Install Git to clone the PostHog MCP repository.
Terminal Proficiency: Basic command-line skills are necessary for setup and configuration.
Docker (Optional): For containerized deployments, install Docker Desktop.
Apidog (Recommended): Download Apidog to test PostHog API endpoints during setup.

button

With these prerequisites in place, you’re ready to install the server.

Installing the PostHog MCP Server: Step-by-Step

Setting up the PostHog MCP server involves cloning the repository, configuring your environment, and installing dependencies. Follow these steps to ensure a smooth installation.

1. Clone the PostHog MCP Repository

Begin by cloning the official PostHog MCP repository from GitHub. Open your terminal and execute:

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

If you prefer HTTPS or lack SSH access, use:

git clone https://github.com/PostHog/posthog-mcp.git

Navigate to the project directory:

cd posthog-mcp

2. Create a Virtual Environment

To isolate dependencies, set up a Python virtual environment using uv. Run:

uv venv
source .venv/bin/activate

For Windows users, activate the environment with:

.\.venv\Scripts\activate

This ensures dependencies don’t conflict with your system’s Python packages.

3. Install Python Dependencies

Install the required packages by running:

uv pip install .

This command installs the PostHog MCP server and its dependencies, ensuring compatibility with your Python version.

4. Configure the PostHog API Key

Obtain a personal API key from PostHog’s settings .

Create a .env file in the project root and add:

POSTHOG_API_TOKEN=Bearer your-personal-api-key

Replace your-personal-api-key with your actual key. This token authenticates the server with PostHog’s API endpoints.

5. Test the Server Locally

Verify the installation by launching the server:

uv run posthog_mcp

If successful, the terminal displays a message indicating the server is running, typically on localhost:8000. If errors occur, double-check your API key, dependencies, and Python version.

6. Optional: Run in a Docker Container

For a containerized setup, pull the official PostHog MCP image and run it with your API key:

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

This approach isolates the server, making it ideal for production or testing environments.

With the server installed, let’s configure your desktop client to connect to it.

Configuring Your Desktop Client for the PostHog MCP Server

The PostHog MCP server integrates with desktop clients like Claude Desktop, Cursor, or Windsurf. Below, we’ll use Claude Desktop as an example to demonstrate the configuration process.

1. Locate the Configuration File

In Claude Desktop, navigate to “Settings” and select “Edit Config.” Alternatively, find the configuration file manually:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\logs
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add the PostHog MCP Server Configuration

Edit the configuration file to include the PostHog MCP server. Insert the following JSON:

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

Replace /path/to/uv with the absolute path to uv (find it with which uv) and /path/to/your/posthog-mcp with the full path to the cloned repository.

3. Save and Restart Claude Desktop

Save the configuration file and restart Claude Desktop. A hammer icon (🔨) should appear in the interface, indicating the MCP server is active. If it’s missing, check the logs at:

macOS: ~/Library/Logs/Claude/mcp*.log
Windows: %APPDATA%\Claude\logs

4. Test the Connection

To confirm the setup, enter a natural language command in Claude Desktop, such as:

List all PostHog projects in my organization

The server should respond with a list of your PostHog projects, confirming successful integration.

5. Configure Alternative Clients (Optional)

For Cursor or Windsurf, refer to their documentation for MCP server integration. The process typically involves adding similar configuration details, pointing to the PostHog MCP server executable.

With your client connected, let’s explore how to use the server effectively.

Practical Use Cases for the PostHog MCP Server

The PostHog MCP server excels at automating and simplifying analytics tasks. Below are five practical scenarios demonstrating its capabilities.

1. Creating Timestamped Annotations

Annotations in PostHog mark significant events, such as product launches or marketing campaigns. Use the MCP server to create annotations effortlessly. In Claude Desktop, input:

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

The server processes the command, interacts with PostHog’s API, and adds the annotation with the specified timestamp and description.

2. Querying and Managing Feature Flags

Feature flags enable dynamic control over application features. Instead of manually checking flags, query them with:

List all active feature flags in project 12345

The server returns a list of flags, including their names and descriptions. You can extend this by asking:

Generate a Python snippet to toggle feature flag 'new-ui' in project 12345

The MCP server provides the code, leveraging PostHog’s API, which you can integrate into your application.

3. Analyzing Application Errors

Track and debug errors without leaving your development environment. Command:

Show the top 5 recent errors in project 67890 with their stack traces

The server queries PostHog’s error tracking data, returning a detailed summary, which you can use to identify and resolve issues quickly.

4. Managing PostHog Projects

For organizations with multiple PostHog projects, the MCP server simplifies oversight. For example:

List all projects in my PostHog organization with their creation dates

The server retrieves project metadata, helping you manage resources or audit usage.

5. Automating Insight Queries

PostHog’s insights feature allows you to analyze user behavior. Use the MCP server to query insights directly:

Show the trend of user sign-ups in project 98765 over the last 30 days

The server fetches the data and presents it in a structured format, ready for further analysis or reporting.

These use cases highlight the server’s versatility in streamlining analytics workflows. Next, let’s optimize its performance.

Optimizing the PostHog MCP Server for Performance

To maximize the PostHog MCP server’s efficiency, implement these best practices.

1. Secure Your API Key

Avoid hardcoding your PostHog API key in scripts or configuration files. Use environment variables (e.g., the .env file) and limit the key’s scope to necessary endpoints. Test key permissions with Apidog to ensure minimal exposure.

2. Monitor and Limit Resource Usage

The MCP server can consume significant CPU and memory, especially during heavy API interactions. Monitor system performance using tools like htop or Docker’s resource limits. For containerized setups, cap resources with:

docker run -i --rm --memory="512m" --cpus="1" -e PERSONAL_API_KEY=your-personal-api-key ghcr.io/metorial/mcp-container--posthog--posthog-mcp--posthog-mcp posthog-mcp

3. Keep the Server Updated

The PostHog MCP repository frequently receives updates for new features, bug fixes, and API compatibility. Regularly pull changes with:

git pull origin main
uv pip install .

Check the GitHub repository for release notes to stay informed.

4. Use Streamable HTTP Transport

The server supports the deprecated Server-Sent Events (SSE) protocol but performs better with Streamable HTTP transport. Update your client configuration to use Streamable HTTP if supported, reducing latency and improving reliability.

5. Cache API Responses Locally

For frequently accessed data (e.g., project lists), implement local caching to reduce API calls. Modify the server’s code to store responses in a lightweight database like SQLite, ensuring compliance with PostHog’s API rate limits.

6. Scale with Load Balancers

For teams with multiple developers, deploy the PostHog MCP server behind a load balancer to distribute requests. Use tools like Nginx or HAProxy to manage traffic, ensuring high availability.

By applying these optimizations, you enhance the server’s performance and reliability. Let’s address common issues next.

Troubleshooting Common Issues with the PostHog MCP Server

Even with careful setup, you may encounter challenges. Below are common issues and their solutions.

1. Hammer Icon Missing in Claude Desktop

If the hammer icon (🔨) doesn’t appear, verify:

The claude_desktop_config.json file uses absolute paths for command and args.
The PostHog API key has sufficient permissions (test with Apidog).
Claude Desktop is restarted after configuration changes.

Check logs at ~/Library/Logs/Claude/mcp*.log (macOS) or %APPDATA%\Claude\logs (Windows) for detailed errors.

2. Authentication Failures

If the server fails to authenticate, ensure the POSTHOG_API_TOKEN in your .env file is correct and prefixed with Bearer. Use Apidog to test the key by making a GET request to https://app.posthog.com/api/projects.

3. Dependency Installation Errors

If uv pip install fails due to conflicts, reset the virtual environment:

rm -rf .venv
uv venv
source .venv/bin/activate
uv pip install .

Ensure your Python version is 3.8 or higher.

4. Slow or Unresponsive Server

If the server is sluggish, check:

System resources (CPU/memory usage).
Internet connectivity, as the server relies on PostHog’s API.
Container resource limits if using Docker.

Restart the server or switch to a containerized setup to isolate issues.

5. Incompatible Client Versions

Ensure your desktop client (e.g., Claude Desktop) supports the MCP protocol version used by the server. Check the client’s documentation and update to the latest version if necessary.

6. Rate Limit Exceeded Errors

PostHog’s API enforces rate limits. If you encounter 429 Too Many Requests errors, implement exponential backoff in the server’s code or reduce query frequency. Contact PostHog support to request higher limits if needed.

These solutions should resolve most issues, ensuring smooth operation. Let’s conclude.

Conclusion

The PostHog MCP server revolutionizes how developers and data teams interact with PostHog’s analytics platform. By enabling natural language commands to manage projects, create annotations, query feature flags, analyze errors, and fetch insights, it streamlines workflows and boosts productivity. This comprehensive guide covered installation, configuration, practical use cases, optimization strategies, and troubleshooting, equipping you to harness the server’s full potential.

To simplify your API testing during setup, download Apidog for free. It complements the PostHog MCP server by providing an intuitive interface for verifying PostHog API endpoints.

button