posthog-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PostHog Automation via Rube MCP

通过Rube MCP实现PostHog自动化

Automate PostHog product analytics and feature flag management through Composio's PostHog toolkit via Rube MCP.

通过Rube MCP，借助Composio的PostHog工具包实现PostHog产品分析和功能标志管理的自动化。

Prerequisites

前置条件

Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
Active PostHog connection via
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
posthog
```
Always call
```
RUBE_SEARCH_TOOLS
```
first to get current tool schemas

必须已连接Rube MCP（需可使用RUBE_SEARCH_TOOLS）
通过
```
RUBE_MANAGE_CONNECTIONS
```
使用
```
posthog
```
工具包建立活跃的PostHog连接
请始终先调用
```
RUBE_SEARCH_TOOLS
```
以获取当前工具架构

Setup

设置步骤

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.

Verify Rube MCP is available by confirming
```
RUBE_SEARCH_TOOLS
```
responds
Call
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
posthog
```
If connection is not ACTIVE, follow the returned auth link to complete PostHog authentication
Confirm connection status shows ACTIVE before running any workflows

获取Rube MCP：在客户端配置中添加

https://rube.app/mcp

作为MCP服务器。无需API密钥——只需添加该端点即可使用。

通过确认
```
RUBE_SEARCH_TOOLS
```
有响应，验证Rube MCP是否可用
使用
```
posthog
```
工具包调用
```
RUBE_MANAGE_CONNECTIONS
```
如果连接状态不是ACTIVE，请按照返回的认证链接完成PostHog认证
在运行任何工作流之前，确认连接状态显示为ACTIVE

Core Workflows

核心工作流

1. Capture Events

1. 捕获事件

When to use: User wants to send event data to PostHog for analytics tracking

Tool sequence:

```
POSTHOG_CAPTURE_EVENT
```
- Send one or more events to PostHog [Required]

Key parameters:

```
event
```
: Event name (e.g., '$pageview', 'user_signed_up', 'purchase_completed')
```
distinct_id
```
: Unique user identifier (required)
```
properties
```
: Object with event-specific properties
```
timestamp
```
: ISO 8601 timestamp (optional; defaults to server time)

Pitfalls:

```
distinct_id
```
is required for every event; identifies the user/device
PostHog system events use
```
$
```
prefix (e.g., '$pageview', '$identify')
Custom events should NOT use the
```
$
```
prefix
Properties are freeform; maintain consistent schemas across events
Events are processed asynchronously; ingestion delay is typically seconds

适用场景：用户希望将事件数据发送到PostHog进行分析追踪

工具流程:

```
POSTHOG_CAPTURE_EVENT
```
- 向PostHog发送一个或多个事件 [必填]

关键参数:

```
event
```
: 事件名称（例如：'$pageview'、'user_signed_up'、'purchase_completed'）
```
distinct_id
```
: 唯一用户标识符（必填）
```
properties
```
: 包含事件特定属性的对象
```
timestamp
```
: ISO 8601时间戳（可选；默认使用服务器时间）

注意事项:

每个事件都需要
```
distinct_id
```
；用于标识用户/设备
PostHog系统事件使用
```
$
```
前缀（例如：'$pageview'、'$identify'）
自定义事件不应使用
```
$
```
前缀
属性为自由格式；需在所有事件中保持一致的架构
事件为异步处理；通常延迟数秒完成 ingestion

2. List and Filter Events

2. 列出并筛选事件

When to use: User wants to browse or search through captured events

Tool sequence:

```
POSTHOG_LIST_AND_FILTER_PROJECT_EVENTS
```
- Query events with filters [Required]

Key parameters:

```
project_id
```
: PostHog project ID (required)
```
event
```
: Filter by event name
```
person_id
```
: Filter by person ID
```
after
```
: Events after this ISO 8601 timestamp
```
before
```
: Events before this ISO 8601 timestamp
```
limit
```
: Maximum events to return
```
offset
```
: Pagination offset

Pitfalls:

```
project_id
```
is required; resolve via LIST_PROJECTS first
Date filters use ISO 8601 format (e.g., '2024-01-15T00:00:00Z')
Large event volumes require pagination; use
```
offset
```
and
```
limit
```
Results are returned in reverse chronological order by default
Event properties are nested; parse carefully

适用场景：用户希望浏览或搜索已捕获的事件

工具流程:

```
POSTHOG_LIST_AND_FILTER_PROJECT_EVENTS
```
- 使用筛选条件查询事件 [必填]

关键参数:

```
project_id
```
: PostHog项目ID（必填）
```
event
```
: 按事件名称筛选
```
person_id
```
: 按用户ID筛选
```
after
```
: 此ISO 8601时间戳之后的事件
```
before
```
: 此ISO 8601时间戳之前的事件
```
limit
```
: 返回的最大事件数
```
offset
```
: 分页偏移量

注意事项:

```
project_id
```
为必填项；需先通过LIST_PROJECTS获取
日期筛选使用ISO 8601格式（例如：'2024-01-15T00:00:00Z'）
大量事件需要分页；使用
```
offset
```
和
```
limit
```
结果默认按时间倒序返回
事件属性为嵌套结构；需仔细解析

3. Manage Feature Flags

3. 管理功能标志

When to use: User wants to create, view, or manage feature flags

Tool sequence:

POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS

- List existing feature flags [Required]

```
POSTHOG_RETRIEVE_FEATURE_FLAG_DETAILS
```
- Get detailed flag configuration [Optional]

POSTHOG_CREATE_FEATURE_FLAGS_FOR_PROJECT

- Create a new feature flag [Optional]

Key parameters:

For listing:
```
project_id
```
(required)
For details:
```
project_id
```
,
```
id
```
(feature flag ID)
For creation:
- ```
project_id
```
  : Target project
- ```
key
```
  : Flag key (e.g., 'new-dashboard-beta')
- ```
name
```
  : Human-readable name
- ```
filters
```
  : Targeting rules and rollout percentage
- ```
active
```
  : Whether the flag is enabled

Pitfalls:

Feature flag
```
key
```
must be unique within a project
Flag keys should use kebab-case (e.g., 'my-feature-flag')
```
filters
```
define targeting groups with properties and rollout percentages
Creating a flag with
```
active: true
```
immediately enables it for matching users
Flag changes take effect within seconds due to PostHog's polling mechanism

适用场景：用户希望创建、查看或管理功能标志

工具流程:

POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS

- 列出现有功能标志 [必填]

```
POSTHOG_RETRIEVE_FEATURE_FLAG_DETAILS
```
- 获取标志的详细配置 [可选]

POSTHOG_CREATE_FEATURE_FLAGS_FOR_PROJECT

- 创建新的功能标志 [可选]

关键参数:

列出标志：
```
project_id
```
（必填）
获取详情：
```
project_id
```
、
```
id
```
（功能标志ID）
创建标志:
- ```
project_id
```
  : 目标项目
- ```
key
```
  : 标志键（例如：'new-dashboard-beta'）
- ```
name
```
  : 易读的名称
- ```
filters
```
  : 目标规则和发布百分比
- ```
active
```
  : 标志是否启用

注意事项:

功能标志的
```
key
```
在项目内必须唯一
标志键应使用短横线分隔格式（kebab-case，例如：'my-feature-flag'）
```
filters
```
通过属性和发布百分比定义目标用户组
创建
```
active: true
```
的标志会立即对匹配用户启用该功能
由于PostHog的轮询机制，标志更改会在数秒内生效

4. Manage Projects

4. 管理项目

When to use: User wants to list or inspect PostHog projects and organizations

Tool sequence:

POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION

- List all projects [Required]

Key parameters:

```
organization_id
```
: Organization identifier (may be optional depending on auth)
```
limit
```
: Number of results per page
```
offset
```
: Pagination offset

Pitfalls:

Project IDs are numeric; used as parameters in most other endpoints
Organization ID may be required; check your PostHog setup
Pagination is offset-based; iterate until results are empty
Project settings include API keys and configuration details

适用场景：用户希望列出或查看PostHog项目和组织

工具流程:

POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION

- 列出所有项目 [必填]

关键参数:

```
organization_id
```
: 组织标识符（根据认证方式可能可选）
```
limit
```
: 每页结果数
```
offset
```
: 分页偏移量

注意事项:

项目ID为数字；在大多数其他端点中用作参数
可能需要组织ID；请检查你的PostHog设置
分页基于偏移量；需循环直到结果为空
项目设置包含API密钥和配置详情

5. User Profile and Authentication

5. 用户配置文件与认证

When to use: User wants to check current user details or verify API access

Tool sequence:

```
POSTHOG_WHOAMI
```
- Get current API user information [Optional]
```
POSTHOG_RETRIEVE_CURRENT_USER_PROFILE
```
- Get detailed user profile [Optional]

Key parameters:

No required parameters for either call
Returns current authenticated user's details, permissions, and organization info

Pitfalls:

WHOAMI is a lightweight check; use for verifying API connectivity
User profile includes organization membership and permissions
These endpoints confirm the API key's access level and scope

适用场景：用户希望查看当前用户详情或验证API访问权限

工具流程:

```
POSTHOG_WHOAMI
```
- 获取当前API用户信息 [可选]
```
POSTHOG_RETRIEVE_CURRENT_USER_PROFILE
```
- 获取详细用户配置文件 [可选]

关键参数:

两个调用都无需必填参数
返回当前已认证用户的详情、权限和组织信息

注意事项:

WHOAMI是轻量级检查；用于验证API连接性
用户配置文件包含组织成员身份和权限
这些端点可确认API密钥的访问级别和范围

Common Patterns

常见模式

ID Resolution

ID解析

Organization -> Project ID:

1. Call POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION
2. Find project by name in results
3. Extract id (numeric) for use in other endpoints

Feature flag name -> Flag ID:

1. Call POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS with project_id
2. Find flag by key or name
3. Extract id for detailed operations

组织 -> 项目ID:

1. Call POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION
2. Find project by name in results
3. Extract id (numeric) for use in other endpoints

功能标志名称 -> 标志ID:

1. Call POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS with project_id
2. Find flag by key or name
3. Extract id for detailed operations

Feature Flag Targeting

功能标志目标定位

Feature flags support sophisticated targeting:

json

{
  "filters": {
    "groups": [
      {
        "properties": [
          {"key": "email", "value": "@company.com", "operator": "icontains"}
        ],
        "rollout_percentage": 100
      },
      {
        "properties": [],
        "rollout_percentage": 10
      }
    ]
  }
}

Groups are evaluated in order; first matching group determines the rollout
Properties filter users by their traits
Rollout percentage determines what fraction of matching users see the flag

功能标志支持复杂的目标定位:

json

{
  "filters": {
    "groups": [
      {
        "properties": [
          {"key": "email", "value": "@company.com", "operator": "icontains"}
        ],
        "rollout_percentage": 100
      },
      {
        "properties": [],
        "rollout_percentage": 10
      }
    ]
  }
}

用户组按顺序评估；第一个匹配的组决定发布范围
属性根据用户特征筛选用户
发布百分比决定匹配用户中能看到该标志的比例

Pagination

分页

Events: Use
```
offset
```
and
```
limit
```
(offset-based)
Feature flags: Use
```
offset
```
and
```
limit
```
(offset-based)
Projects: Use
```
offset
```
and
```
limit
```
(offset-based)
Continue until results array is empty or smaller than
```
limit
```

事件：使用
```
offset
```
和
```
limit
```
（基于偏移量）
功能标志：使用
```
offset
```
和
```
limit
```
（基于偏移量）
项目：使用
```
offset
```
和
```
limit
```
（基于偏移量）
持续调用直到结果数组为空或数量少于
```
limit
```

Known Pitfalls

已知注意事项

Project IDs:

Required for most API endpoints
Always resolve project names to numeric IDs first
Multiple projects can exist in one organization

Event Naming:

System events use
```
$
```
prefix ($pageview, $identify, $autocapture)
Custom events should NOT use
```
$
```
prefix
Event names are case-sensitive; maintain consistency

Feature Flags:

Flag keys must be unique within a project
Use kebab-case for flag keys
Changes propagate within seconds
Deleting a flag is permanent; consider disabling instead

Rate Limits:

Event ingestion has throughput limits
Batch events where possible for efficiency
API endpoints have per-minute rate limits

Response Parsing:

Response data may be nested under
```
data
```
or
```
results
```
key
Paginated responses include
```
count
```
,
```
next
```
,
```
previous
```
fields
Event properties are nested objects; access carefully
Parse defensively with fallbacks for optional fields

项目ID:

大多数API端点都需要项目ID
请始终先将项目名称解析为数字ID
一个组织内可存在多个项目

事件命名:

系统事件使用
```
$
```
前缀（$pageview、$identify、$autocapture）
自定义事件不应使用
```
$
```
前缀
事件名称区分大小写；需保持一致性

功能标志:

标志键在项目内必须唯一
标志键使用短横线分隔格式（kebab-case）
更改会在数秒内生效
删除标志是永久性操作；建议先禁用而非删除

速率限制:

事件 ingestion 有吞吐量限制
尽可能批量处理事件以提高效率
API端点有每分钟速率限制

响应解析:

响应数据可能嵌套在
```
data
```
或
```
results
```
键下
分页响应包含
```
count
```
、
```
next
```
、
```
previous
```
字段
事件属性为嵌套对象；需谨慎访问
解析时需为可选字段设置回退逻辑

Quick Reference

快速参考

Task	Tool Slug	Key Params
Capture event	POSTHOG_CAPTURE_EVENT	event, distinct_id, properties
List events	POSTHOG_LIST_AND_FILTER_PROJECT_EVENTS	project_id, event, after, before
List feature flags	POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS	project_id
Get flag details	POSTHOG_RETRIEVE_FEATURE_FLAG_DETAILS	project_id, id
Create flag	POSTHOG_CREATE_FEATURE_FLAGS_FOR_PROJECT	project_id, key, filters
List projects	POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION	organization_id
Who am I	POSTHOG_WHOAMI	(none)
User profile	POSTHOG_RETRIEVE_CURRENT_USER_PROFILE	(none)

任务	工具标识	关键参数
捕获事件	POSTHOG_CAPTURE_EVENT	event, distinct_id, properties
列出事件	POSTHOG_LIST_AND_FILTER_PROJECT_EVENTS	project_id, event, after, before
列出功能标志	POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS	project_id
获取标志详情	POSTHOG_RETRIEVE_FEATURE_FLAG_DETAILS	project_id, id
创建标志	POSTHOG_CREATE_FEATURE_FLAGS_FOR_PROJECT	project_id, key, filters
列出项目	POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION	organization_id
验证身份	POSTHOG_WHOAMI	(无)
用户配置文件	POSTHOG_RETRIEVE_CURRENT_USER_PROFILE	(无)