Allows listing projects, creating annotations with optional timestamps, getting and searching insights, and searching documentation online via PostHog's API.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@posthog-mcp List my PostHog projects"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server for interacting with PostHog. Create annotations and manage projects directly through Claude Desktop!
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...]
Related MCP server: PostHog MCP Server
Prerequisites
Python 3.10 or higher
uv package manager
PostHog API Key with annotation:write and project:read scopes obtained from your project settings
Installation
# clone the repo
git clone git@github.com: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 .Configuration
Create a .env file in the project root:
PERSONAL_API_KEY=phx_your_posthog_api_key_hereClaude 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/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.
After setup, you'll see a hammer 🔨 icon in Claude Desktop. The following commands are available:
Ask Claude:
"List my PostHog projects"Ask Claude:
"List my PostHog insights" or "Search for revenue insights in my PostHog"
You can ask:
"how can i do reverse proxy in nextjs in posthog?"
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'"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
Feel free to open issues and PRs! We follow PostHog's contribution guidelines.
Create a PostHog annotation.
Args: project_id: The ID of the project as an integer (e.g. 99423) content: The content/text of the annotation date_marker: Optional ISO-8601 timestamp for the annotation (e.g. 2024-03-20T14:15:22Z)
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| content | Yes | ||
| date_marker | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It only says 'Create' and lists parameters, omitting details like required permissions, side effects, or response characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with purpose. The Args format is concise but uses a technical docstring style; still every part adds value without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 parameters, no output schema, and no annotations, the description covers parameters but lacks behavioral context, output details, and any guidance on usage prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds parameter meanings and examples (e.g., project_id as integer with example, date_marker format). However, restrictions (e.g., content limits) are missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a PostHog annotation', using a specific verb and resource that distinguishes it from sibling tools focused on insights and projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives, preconditions, or context. Sibling tools are different, but the description does not highlight usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details for a specific PostHog insight.
Args: project_id: The ID of the project as an integer (e.g. 99423) insight_id: The ID of the insight as an integer (e.g. 12345)
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| insight_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only states 'get details' but omits whether the operation is read-only, any authorization needs, rate limits, error handling, or response format. This is insufficient for a tool with zero annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two sentences plus arg list), front-loaded with the purpose, and every sentence adds necessary information. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has two simple integer parameters and no output schema. The description covers the basics but lacks details on return values (what constitutes 'details'), possible errors, or pagination. It is minimally complete given the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds value by explaining each parameter (project_id, insight_id) as integers with examples. However, it does not clarify their source or validation rules, just barely meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves details for a specific PostHog insight, using the verb 'get' and specifying the resource. It effectively distinguishes from sibling tools like list_posthog_insights (list) and search_posthog_insights (search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for a single insight but does not explicitly clarify when to use this tool over alternatives like listing or searching. No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available PostHog insights for a project.
Args: project_id: The ID of the project as an integer (e.g. 99423) search: Optional search query to filter insights
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| search | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It implies a read operation but does not disclose potential limitations like pagination, rate limits, or authentication requirements. Bare minimum acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one-line purpose plus clear parameter listing. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description does not mention what is returned (e.g., list of insight summaries or IDs). Also lacks any note on pagination or handling of large result sets.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds basic meaning to the two parameters (project_id with example, search as optional filter). However, it lacks details on search format or behavior of null default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all available PostHog insights for a project. However, it does not differentiate from the sibling search_posthog_insights which likely provides similar functionality with more filters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like search_posthog_insights or get_posthog_insight_details. The description lacks usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available PostHog projects.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. The word 'list' implies read-only, but no explicit mention of safety, rate limits, or other behaviors. Minimal but acceptable for a simple operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no waste. Perfectly concise and front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so description should clarify what is returned (e.g., names, IDs). It does not, leaving ambiguity. For a zero-parameter tool, it is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, baseline is 4. The description adds no parameter info, but none is needed. It explains the scope ('all available') which adds meaning beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists all available PostHog projects with a specific verb and resource. No sibling tools have similar purpose, so differentiation is natural.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need to list projects). No explicit when-not or alternatives, but the context is clear and no exclusions are necessary given the tool's simplicity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for PostHog insights by name.
Args: project_id: The ID of the project as an integer (e.g. 99423) search: The search query to filter insights by name
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| search | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description must fully cover behavioral traits. It only mentions searching by name but omits details like pagination, result limits, case sensitivity, or output format. The minimal disclosure is insufficient for reliable use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and to the point, consisting of a single-purpose sentence followed by parameter explanations. It avoids redundancy, though a structured list would improve readability slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search function with two parameters, the description provides the essential inputs and purpose. However, it lacks context on output structure, expected behavior when no results are found, and any constraints, leaving some gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description compensates for the schema's lack of property descriptions by explaining project_id as an integer with an example and search as a filter by name. This adds meaningful context beyond the raw schema, though more specifics (e.g., supported wildcards) could enhance clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for PostHog insights by name. This is a specific action on a specific resource. While it is distinguishable from siblings like list_posthog_insights (which lists all) and get_posthog_insight_details (which gets details of one), it does not explicitly differentiate itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this search tool versus listing all insights or retrieving details. There is no indication of prerequisites or limitations, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tools are mostly distinct. However, list_posthog_insights and search_posthog_insights have overlapping functionality since list already supports a search filter, which could cause confusion.
All tools follow a consistent verb_posthog_noun pattern in snake_case, making them predictable and easy to understand.
5 tools is on the low side for a platform like PostHog which has many resources. The server feels undersized for its stated purpose.
Missing key CRUD operations: annotations lack read, update, delete; insights lack create, update, delete; projects only have list. Significant gaps in coverage.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Connect Claude to Fathom meeting recordings, transcripts, and summaries
Run UX research from Claude — create card sort studies, list studies, pull headline stats.
Connect Claude to your Platform7n workspaces — chat, links, and tasks. One-click OAuth.
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/israpasos/posthog-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
