MCP PostHog Server (TypeScript)

A Model Context Protocol (MCP) server built in TypeScript that exposes PostHog operations as tools. MCP clients (e.g., LLM-based chat agents) can connect with their personal PostHog API keys to read and write data in a user's PostHog project.

Features

• Securely proxy PostHog API calls via MCP
• Tool definitions for:
  • Listing and creating cohorts
  • Add more implemented tools here
• Error handling and basic logging
• Ready for containerization with Docker

Prerequisites

• Node.js v16 or later
• npm
• A PostHog Project ID, Host URL, and Personal API Key.
  • Find your Project ID under Project Settings.
  • Find your Host URL (e.g., https://us.posthog.com, https://eu.posthog.com, or your self-hosted URL).
  • Generate a Personal API Key under Account Settings -> Personal API Keys. (Copy the entire key).
• MCP TypeScript SDK (@modelcontextprotocol/sdk)

Installation

# Clone the repo
git clone <your-repo-url> mcp-posthog-server
cd mcp-posthog-server

# Install dependencies
npm install

# Build the TypeScript code
npm run build

Configuration

This server requires three pieces of configuration, which can be provided either via command-line arguments (host and key only) or environment variables:

1. PostHog Host: The base URL of your PostHog instance (e.g., https://us.posthog.com).
2. PostHog Personal API Key: Your personal key for API access.
3. PostHog Project ID: The numerical ID of your project.

Priority: Command-line arguments (if provided) override environment variables for Host and API Key. Project ID must always be set as an environment variable.

Environment Variables:

Create a .env file in the project root or set these variables in your shell:

# .env file example
POSTHOG_HOST=https://us.posthog.com
POSTHOG_API_KEY=YOUR_FULL_POSTHOG_PERSONAL_API_KEY
POSTHOG_PROJECT_ID=12345

Command-line Arguments (Overrides Host/Key from Env):

When running directly with node or npx, you can pass the host and API key as arguments:

node build/index.js <YOUR_POSTHOG_HOST> <YOUR_POSTHOG_API_KEY>
# Requires POSTHOG_PROJECT_ID to be set in the environment

npx @your-org/mcp-posthog-server <YOUR_POSTHOG_HOST> <YOUR_POSTHOG_API_KEY>
# Requires POSTHOG_PROJECT_ID to be set in the environment
# (Replace @your-org with your actual scope if publishing)

Running the Server

There are several ways to run the server:

1. Using npm (after build):

# Make sure POSTHOG_HOST, POSTHOG_API_KEY, POSTHOG_PROJECT_ID are set in your env
npm start

2. Directly with Node (after build):

# Option A: Using Environment Variables
export POSTHOG_HOST=...
export POSTHOG_API_KEY=...
export POSTHOG_PROJECT_ID=...
node build/index.js

# Option B: Using Command-line Args (Host/Key) + Env Var (Project ID)
export POSTHOG_PROJECT_ID=...
node build/index.js https://us.posthog.com YOUR_FULL_POSTHOG_PERSONAL_API_KEY

3. Using npx (after publishing to npm):

Replace @your-org/mcp-posthog-server with the actual published package name.

export POSTHOG_PROJECT_ID=...
npx @your-org/mcp-posthog-server https://us.posthog.com YOUR_FULL_POSTHOG_PERSONAL_API_KEY

4. Using Docker (Recommended for Deployment):

Build the image:

docker build -t mcp-posthog-server .

Run the container. There are two main ways to provide configuration:

• Option A: Using Environment Variables (via -e flags):

  docker run --rm -it \
    -e POSTHOG_HOST="https://us.posthog.com" \
    -e POSTHOG_API_KEY="YOUR_FULL_POSTHOG_PERSONAL_API_KEY" \
    -e POSTHOG_PROJECT_ID="12345" \
    mcp-posthog-server
  

• Option B: Mounting a .env file (Easier for Local):

  This method reads configuration directly from a .env file in your project root. Ensure the file exists and contains the exact variable names: POSTHOG_HOST, POSTHOG_API_KEY, POSTHOG_PROJECT_ID.

  # Run this command from the project root directory
  docker run --rm -it \
    -v "$(pwd)/.env:/app/.env:ro" \
    mcp-posthog-server
  

Since this server uses stdio for MCP communication by default, you typically don't need to map ports (-p). Your MCP client will connect by executing the appropriate docker run command (either Option A or B, depending on how you prefer to handle secrets when configuring the client).

Project Structure

.
├── src/
│   ├── index.ts            # Server entry point, MCP setup, tool registration
│   ├── posthog-client.ts   # PostHog client/config initialization helper
│   └── tools/
│       └── cohorts.ts      # Cohort tool schemas and handlers
├── Dockerfile              # For building production container image
├── Readme.md               # This file
├── package.json
├── package-lock.json
├── tsconfig.json
└── .env.example            # Example environment variables (optional)

Connecting your MCP-compatible client

Configure your client (e.g., Cursor, Claude Desktop) to run the server. The exact command depends on how you choose to run it (Node, npx, Docker).

Example for Cursor (.cursor/mcp.json) using Docker:

{
  "mcpServers": {
    "posthog": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "POSTHOG_HOST=https://us.posthog.com",
        "-e", "POSTHOG_API_KEY=YOUR_FULL_POSTHOG_PERSONAL_API_KEY",
        "-e", "POSTHOG_PROJECT_ID=12345",
        "mcp-posthog-server"
      ]
    }
  }
}

Example for Cursor (.cursor/mcp.json or ~/.cursor/mcp.json) using Node:

This configuration tells Cursor how to run the built server directly using Node. Make sure the args path points to the correct absolute location of build/index.js on your system.

{
  "mcpServers": {
    "posthog": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-posthog-server/build/index.js"
      ],
      "env": {
          "POSTHOG_HOST": "https://us.posthog.com",
          "POSTHOG_API_KEY": "YOUR_FULL_POSTHOG_PERSONAL_API_KEY",
          "POSTHOG_PROJECT_ID": "12345"
      }
    }
  }
}

After configuring Cursor (you may need to reload the window) and ensuring the server can run (either via Docker or Node with the correct environment variables set), you can invoke tools using the key you defined (e.g., @posthog):

@posthog list cohorts

@posthog create cohort named "High Value Users" with criteria email contains "@company.com"

Extending with Custom Tools

1. Create a new file under src/tools/ (e.g., src/tools/featureFlags.ts).
2. Define Zod schemas for the tool's input.
3. Define and export an async handler function for the tool logic (e.g., export async function getFeatureFlagHandler(args: GetFlagInput)).
   • Use the posthogApiFetch helper or direct API calls.
   • Return results in the { content: [{ type: "text", text: ... }] } format.
4. Import the schema and handler into src/index.ts.
5. Register the tool using server.tool(name, description, schema.shape, handler);.
6. Rebuild the server (npm run build).

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-tool)
3. Commit your changes (git commit -m "feat: add my custom tool")
4. Push to the branch (git push origin feature/my-tool)
5. Open a Pull Request

License

MIT License