Liquidium MCP Server

Tools for PostHog analytics, annotations, and project management.

Liquidium MCP Server

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

Features

  • List Projects: View all available PostHog projects in your organization
  • Create Annotations: Add annotations to your PostHog projects with optional timestamps
  • List and Search Insights: View and search for insights in your PostHog projects
  • Get Insight Details: View detailed information about specific insights

Setup

Option 1: Smithery (Recommended)

The easiest way to use Liquidium MCP is through Smithery:

  1. Visit Liquidium MCP on Smithery
  2. Click "Add to Claude"
  3. Enter your PostHog API Key when prompted
  4. Start using Liquidium tools in Claude!

Option 2: Local Installation

  1. Prerequisites

    • Python 3.10 or higher
    • pip or uv package manager
    • PostHog API Key with annotation:write and project:read scopes obtained from your project settings
  2. Installation

    # clone the repo
    git clone https://github.com/Shudufhadzo/liquidium-mcp.git
    
    cd liquidium-mcp
    
    # Create and activate virtual environment
    python -m venv .venv
    
    # On Windows
    .venv\Scripts\activate
    
    # On macOS/Linux
    source .venv/bin/activate
    
    # Install dependencies
    pip install -e .
    
  3. Configuration

    • Create a .env file in the project root:
      PERSONAL_API_KEY=phx_your_posthog_api_key_here
      
  4. Claude Desktop Setup

    • Install Claude Desktop
    • 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%\Claude\claude_desktop_config.json
    • Add this to your claude_desktop_config.json (adjust paths according to your system):
      {
        "mcpServers": {
          "posthog": {
            "command": "/path/to/python",  # Get this by running: which python
            "args": [
              "-m",
              "posthog_mcp",
              "--directory",
              "/path/to/your/posthog-mcp"  # Full path to this project
            ]
          }
        }
      }
      
      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%\Claude\logs (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.

Related Servers