Posthog Automation

1---
2name: posthog-automation
3description: "Automate PostHog tasks via Rube MCP (Composio): events, feature flags, projects, user profiles, annotations. Always search tools first for current schemas."
4requires:
5  mcp: [rube]
6---
7 
8# PostHog Automation via Rube MCP
9 
10Automate PostHog product analytics and feature flag management through Composio's PostHog toolkit via Rube MCP.
11 
12## Prerequisites
13 
14- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
15- Active PostHog connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `posthog`
16- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
17 
18## Setup
19 
20**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
21 
22 
231. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
242. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `posthog`
253. If connection is not ACTIVE, follow the returned auth link to complete PostHog authentication
264. Confirm connection status shows ACTIVE before running any workflows
27 
28## Core Workflows
29 
30### 1. Capture Events
31 
32**When to use**: User wants to send event data to PostHog for analytics tracking
33 
34**Tool sequence**:
351. `POSTHOG_CAPTURE_EVENT` - Send one or more events to PostHog [Required]
36 
37**Key parameters**:
38- `event`: Event name (e.g., '$pageview', 'user_signed_up', 'purchase_completed')
39- `distinct_id`: Unique user identifier (required)
40- `properties`: Object with event-specific properties
41- `timestamp`: ISO 8601 timestamp (optional; defaults to server time)
42 
43**Pitfalls**:
44- `distinct_id` is required for every event; identifies the user/device
45- PostHog system events use `$` prefix (e.g., '$pageview', '$identify')
46- Custom events should NOT use the `$` prefix
47- Properties are freeform; maintain consistent schemas across events
48- Events are processed asynchronously; ingestion delay is typically seconds
49 
50### 2. List and Filter Events
51 
52**When to use**: User wants to browse or search through captured events
53 
54**Tool sequence**:
551. `POSTHOG_LIST_AND_FILTER_PROJECT_EVENTS` - Query events with filters [Required]
56 
57**Key parameters**:
58- `project_id`: PostHog project ID (required)
59- `event`: Filter by event name
60- `person_id`: Filter by person ID
61- `after`: Events after this ISO 8601 timestamp
62- `before`: Events before this ISO 8601 timestamp
63- `limit`: Maximum events to return
64- `offset`: Pagination offset
65 
66**Pitfalls**:
67- `project_id` is required; resolve via LIST_PROJECTS first
68- Date filters use ISO 8601 format (e.g., '2024-01-15T00:00:00Z')
69- Large event volumes require pagination; use `offset` and `limit`
70- Results are returned in reverse chronological order by default
71- Event properties are nested; parse carefully
72 
73### 3. Manage Feature Flags
74 
75**When to use**: User wants to create, view, or manage feature flags
76 
77**Tool sequence**:
781. `POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS` - List existing feature flags [Required]
792. `POSTHOG_RETRIEVE_FEATURE_FLAG_DETAILS` - Get detailed flag configuration [Optional]
803. `POSTHOG_CREATE_FEATURE_FLAGS_FOR_PROJECT` - Create a new feature flag [Optional]
81 
82**Key parameters**:
83- For listing: `project_id` (required)
84- For details: `project_id`, `id` (feature flag ID)
85- For creation:
86  - `project_id`: Target project
87  - `key`: Flag key (e.g., 'new-dashboard-beta')
88  - `name`: Human-readable name
89  - `filters`: Targeting rules and rollout percentage
90  - `active`: Whether the flag is enabled
91 
92**Pitfalls**:
93- Feature flag `key` must be unique within a project
94- Flag keys should use kebab-case (e.g., 'my-feature-flag')
95- `filters` define targeting groups with properties and rollout percentages
96- Creating a flag with `active: true` immediately enables it for matching users
97- Flag changes take effect within seconds due to PostHog's polling mechanism
98 
99### 4. Manage Projects
100 
101**When to use**: User wants to list or inspect PostHog projects and organizations
102 
103**Tool sequence**:
1041. `POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION` - List all projects [Required]
105 
106**Key parameters**:
107- `organization_id`: Organization identifier (may be optional depending on auth)
108- `limit`: Number of results per page
109- `offset`: Pagination offset
110 
111**Pitfalls**:
112- Project IDs are numeric; used as parameters in most other endpoints
113- Organization ID may be required; check your PostHog setup
114- Pagination is offset-based; iterate until results are empty
115- Project settings include API keys and configuration details
116 
117### 5. User Profile and Authentication
118 
119**When to use**: User wants to check current user details or verify API access
120 
121**Tool sequence**:
1221. `POSTHOG_WHOAMI` - Get current API user information [Optional]
1232. `POSTHOG_RETRIEVE_CURRENT_USER_PROFILE` - Get detailed user profile [Optional]
124 
125**Key parameters**:
126- No required parameters for either call
127- Returns current authenticated user's details, permissions, and organization info
128 
129**Pitfalls**:
130- WHOAMI is a lightweight check; use for verifying API connectivity
131- User profile includes organization membership and permissions
132- These endpoints confirm the API key's access level and scope
133 
134## Common Patterns
135 
136### ID Resolution
137 
138**Organization -> Project ID**:
139```
1401. Call POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION
1412. Find project by name in results
1423. Extract id (numeric) for use in other endpoints
143```
144 
145**Feature flag name -> Flag ID**:
146```
1471. Call POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS with project_id
1482. Find flag by key or name
1493. Extract id for detailed operations
150```
151 
152### Feature Flag Targeting
153 
154Feature flags support sophisticated targeting:
155```json
156{
157  "filters": {
158    "groups": [
159      {
160        "properties": [
161          {"key": "email", "value": "@company.com", "operator": "icontains"}
162        ],
163        "rollout_percentage": 100
164      },
165      {
166        "properties": [],
167        "rollout_percentage": 10
168      }
169    ]
170  }
171}
172```
173- Groups are evaluated in order; first matching group determines the rollout
174- Properties filter users by their traits
175- Rollout percentage determines what fraction of matching users see the flag
176 
177### Pagination
178 
179- Events: Use `offset` and `limit` (offset-based)
180- Feature flags: Use `offset` and `limit` (offset-based)
181- Projects: Use `offset` and `limit` (offset-based)
182- Continue until results array is empty or smaller than `limit`
183 
184## Known Pitfalls
185 
186**Project IDs**:
187- Required for most API endpoints
188- Always resolve project names to numeric IDs first
189- Multiple projects can exist in one organization
190 
191**Event Naming**:
192- System events use `$` prefix ($pageview, $identify, $autocapture)
193- Custom events should NOT use `$` prefix
194- Event names are case-sensitive; maintain consistency
195 
196**Feature Flags**:
197- Flag keys must be unique within a project
198- Use kebab-case for flag keys
199- Changes propagate within seconds
200- Deleting a flag is permanent; consider disabling instead
201 
202**Rate Limits**:
203- Event ingestion has throughput limits
204- Batch events where possible for efficiency
205- API endpoints have per-minute rate limits
206 
207**Response Parsing**:
208- Response data may be nested under `data` or `results` key
209- Paginated responses include `count`, `next`, `previous` fields
210- Event properties are nested objects; access carefully
211- Parse defensively with fallbacks for optional fields
212 
213## Quick Reference
214 
215| Task | Tool Slug | Key Params |
216|------|-----------|------------|
217| Capture event | POSTHOG_CAPTURE_EVENT | event, distinct_id, properties |
218| List events | POSTHOG_LIST_AND_FILTER_PROJECT_EVENTS | project_id, event, after, before |
219| List feature flags | POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS | project_id |
220| Get flag details | POSTHOG_RETRIEVE_FEATURE_FLAG_DETAILS | project_id, id |
221| Create flag | POSTHOG_CREATE_FEATURE_FLAGS_FOR_PROJECT | project_id, key, filters |
222| List projects | POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION | organization_id |
223| Who am I | POSTHOG_WHOAMI | (none) |
224| User profile | POSTHOG_RETRIEVE_CURRENT_USER_PROFILE | (none) |
225