Amplitude Automation

1---
2name: amplitude-automation
3description: "Automate Amplitude tasks via Rube MCP (Composio): events, user activity, cohorts, user identification. Always search tools first for current schemas."
4requires:
5  mcp: [rube]
6---
7 
8# Amplitude Automation via Rube MCP
9 
10Automate Amplitude product analytics through Composio's Amplitude toolkit via Rube MCP.
11 
12## Prerequisites
13 
14- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
15- Active Amplitude connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `amplitude`
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 `amplitude`
253. If connection is not ACTIVE, follow the returned auth link to complete Amplitude authentication
264. Confirm connection status shows ACTIVE before running any workflows
27 
28## Core Workflows
29 
30### 1. Send Events
31 
32**When to use**: User wants to track events or send event data to Amplitude
33 
34**Tool sequence**:
351. `AMPLITUDE_SEND_EVENTS` - Send one or more events to Amplitude [Required]
36 
37**Key parameters**:
38- `events`: Array of event objects, each containing:
39  - `event_type`: Name of the event (e.g., 'page_view', 'purchase')
40  - `user_id`: Unique user identifier (required if no `device_id`)
41  - `device_id`: Device identifier (required if no `user_id`)
42  - `event_properties`: Object with custom event properties
43  - `user_properties`: Object with user properties to set
44  - `time`: Event timestamp in milliseconds since epoch
45 
46**Pitfalls**:
47- At least one of `user_id` or `device_id` is required per event
48- `event_type` is required for every event; cannot be empty
49- `time` must be in milliseconds (13-digit epoch), not seconds
50- Batch limit applies; check schema for maximum events per request
51- Events are processed asynchronously; successful API response does not mean data is immediately queryable
52 
53### 2. Get User Activity
54 
55**When to use**: User wants to view event history for a specific user
56 
57**Tool sequence**:
581. `AMPLITUDE_FIND_USER` - Find user by ID or property [Prerequisite]
592. `AMPLITUDE_GET_USER_ACTIVITY` - Retrieve user's event stream [Required]
60 
61**Key parameters**:
62- `user`: Amplitude internal user ID (from FIND_USER)
63- `offset`: Pagination offset for event list
64- `limit`: Maximum number of events to return
65 
66**Pitfalls**:
67- `user` parameter requires Amplitude's internal user ID, NOT your application's user_id
68- Must call FIND_USER first to resolve your user_id to Amplitude's internal ID
69- Activity is returned in reverse chronological order by default
70- Large activity histories require pagination via `offset`
71 
72### 3. Find and Identify Users
73 
74**When to use**: User wants to look up users or set user properties
75 
76**Tool sequence**:
771. `AMPLITUDE_FIND_USER` - Search for a user by various identifiers [Required]
782. `AMPLITUDE_IDENTIFY` - Set or update user properties [Optional]
79 
80**Key parameters**:
81- For FIND_USER:
82  - `user`: Search term (user_id, email, or Amplitude ID)
83- For IDENTIFY:
84  - `user_id`: Your application's user identifier
85  - `device_id`: Device identifier (alternative to user_id)
86  - `user_properties`: Object with `$set`, `$unset`, `$add`, `$append` operations
87 
88**Pitfalls**:
89- FIND_USER searches across user_id, device_id, and Amplitude ID
90- IDENTIFY uses special property operations (`$set`, `$unset`, `$add`, `$append`)
91- `$set` overwrites existing values; `$setOnce` only sets if not already set
92- At least one of `user_id` or `device_id` is required for IDENTIFY
93- User property changes are eventually consistent; not immediate
94 
95### 4. Manage Cohorts
96 
97**When to use**: User wants to list cohorts, view cohort details, or update cohort membership
98 
99**Tool sequence**:
1001. `AMPLITUDE_LIST_COHORTS` - List all saved cohorts [Required]
1012. `AMPLITUDE_GET_COHORT` - Get detailed cohort information [Optional]
1023. `AMPLITUDE_UPDATE_COHORT_MEMBERSHIP` - Add/remove users from a cohort [Optional]
1034. `AMPLITUDE_CHECK_COHORT_STATUS` - Check async cohort operation status [Optional]
104 
105**Key parameters**:
106- For LIST_COHORTS: No required parameters
107- For GET_COHORT: `cohort_id` (from list results)
108- For UPDATE_COHORT_MEMBERSHIP:
109  - `cohort_id`: Target cohort ID
110  - `memberships`: Object with `add` and/or `remove` arrays of user IDs
111- For CHECK_COHORT_STATUS: `request_id` from update response
112 
113**Pitfalls**:
114- Cohort IDs are required for all cohort-specific operations
115- UPDATE_COHORT_MEMBERSHIP is asynchronous; use CHECK_COHORT_STATUS to verify
116- `request_id` from the update response is needed for status checking
117- Maximum membership changes per request may be limited; chunk large updates
118- Only behavioral cohorts support API membership updates
119 
120### 5. Browse Event Categories
121 
122**When to use**: User wants to discover available event types and categories in Amplitude
123 
124**Tool sequence**:
1251. `AMPLITUDE_GET_EVENT_CATEGORIES` - List all event categories [Required]
126 
127**Key parameters**:
128- No required parameters; returns all configured event categories
129 
130**Pitfalls**:
131- Categories are configured in Amplitude UI; API provides read access
132- Event names within categories are case-sensitive
133- Use these categories to validate event_type values before sending events
134 
135## Common Patterns
136 
137### ID Resolution
138 
139**Application user_id -> Amplitude internal ID**:
140```
1411. Call AMPLITUDE_FIND_USER with user=your_user_id
1422. Extract Amplitude's internal user ID from response
1433. Use internal ID for GET_USER_ACTIVITY
144```
145 
146**Cohort name -> Cohort ID**:
147```
1481. Call AMPLITUDE_LIST_COHORTS
1492. Find cohort by name in results
1503. Extract id for cohort operations
151```
152 
153### User Property Operations
154 
155Amplitude IDENTIFY supports these property operations:
156- `$set`: Set property value (overwrites existing)
157- `$setOnce`: Set only if property not already set
158- `$add`: Increment numeric property
159- `$append`: Append to list property
160- `$unset`: Remove property entirely
161 
162Example structure:
163```json
164{
165  "user_properties": {
166    "$set": {"plan": "premium", "company": "Acme"},
167    "$add": {"login_count": 1}
168  }
169}
170```
171 
172### Async Operation Pattern
173 
174For cohort membership updates:
175```
1761. Call AMPLITUDE_UPDATE_COHORT_MEMBERSHIP -> get request_id
1772. Call AMPLITUDE_CHECK_COHORT_STATUS with request_id
1783. Repeat step 2 until status is 'complete' or 'error'
179```
180 
181## Known Pitfalls
182 
183**User IDs**:
184- Amplitude has its own internal user IDs separate from your application's
185- FIND_USER resolves your IDs to Amplitude's internal IDs
186- GET_USER_ACTIVITY requires Amplitude's internal ID, not your user_id
187 
188**Event Timestamps**:
189- Must be in milliseconds since epoch (13 digits)
190- Seconds (10 digits) will be interpreted as very old dates
191- Omitting timestamp uses server receive time
192 
193**Rate Limits**:
194- Event ingestion has throughput limits per project
195- Batch events where possible to reduce API calls
196- Cohort membership updates have async processing limits
197 
198**Response Parsing**:
199- Response data may be nested under `data` key
200- User activity returns events in reverse chronological order
201- Cohort lists may include archived cohorts; check status field
202- Parse defensively with fallbacks for optional fields
203 
204## Quick Reference
205 
206| Task | Tool Slug | Key Params |
207|------|-----------|------------|
208| Send events | AMPLITUDE_SEND_EVENTS | events (array) |
209| Find user | AMPLITUDE_FIND_USER | user |
210| Get user activity | AMPLITUDE_GET_USER_ACTIVITY | user, offset, limit |
211| Identify user | AMPLITUDE_IDENTIFY | user_id, user_properties |
212| List cohorts | AMPLITUDE_LIST_COHORTS | (none) |
213| Get cohort | AMPLITUDE_GET_COHORT | cohort_id |
214| Update cohort members | AMPLITUDE_UPDATE_COHORT_MEMBERSHIP | cohort_id, memberships |
215| Check cohort status | AMPLITUDE_CHECK_COHORT_STATUS | request_id |
216| List event categories | AMPLITUDE_GET_EVENT_CATEGORIES | (none) |
217