npm package: @playful-ai-games/amplitude-mcp
Description: Model Context Protocol server for Amplitude
Latest version: 0.1.2

# Amplitude MCP Server

A Model Context Protocol (MCP) server for Amplitude Analytics API v2, providing comprehensive tools for event analytics, funnel analysis, retention tracking, and user activity monitoring.

## Overview

This MCP server enables AI assistants and other MCP clients to interact with the Amplitude Dashboard REST API v2, allowing them to:

- Query event data with filters and metrics
- Perform advanced segmentation with breakdowns and grouping
- Analyze conversion funnels between events
- Track user retention patterns
- Retrieve detailed user activity history
- Access event data through structured resources

## Installation

### From GitHub Package Registry

```json
{
  "mcpServers": {
    "amplitude": {
      "command": "npx",
      "args": [
        "-y",
        "amplitude-mcp-playful",
        "--amplitude-api-key=YOUR_API_KEY",
        "--amplitude-secret-key=YOUR_SECRET_KEY"
      ]
    }
  }
}
```

### Command Line Usage

```bash
# Using npx (recommended)
npx playful-ai-games/amplitude-mcp --amplitude-api-key=YOUR_API_KEY --amplitude-secret-key=YOUR_SECRET_KEY

# Or install globally
npm install -g playful-ai-games/amplitude-mcp
amplitude-mcp --amplitude-api-key=YOUR_API_KEY --amplitude-secret-key=YOUR_SECRET_KEY
```

### Required Credentials

Amplitude API credentials must be provided using command line arguments:

- `--amplitude-api-key`: Your Amplitude API key (required)
- `--amplitude-secret-key`: Your Amplitude secret key (required)
- `--use-eu-server`: Use EU residency server (optional, defaults to US server)

## Available Tools

### 1. query_events

Event querying with filters and metrics.

**Parameters:**

- `events` (array): Array of events to query
  - `eventType` (string): Type of event
  - `propertyFilters` (array, optional): Filters for event properties
- `start` (string): Start date in YYYYMMDD format
- `end` (string): End date in YYYYMMDD format
- `metric` (string, optional): Metric type (uniques, totals, pct_dau, average, frequency, propsum, propcnt) - defaults to uniques
- `interval` (string, optional): Grouping interval (hour, day, week, month)
- `groupBy` (string, optional): Property to group results by
- `limit` (number, optional): Limit for group by values (1-1000)

**Example:**

```json
{
  "events": [
    {
      "eventType": "user_login",
      "propertyFilters": [
        {
          "propertyName": "device_type",
          "value": "mobile",
          "op": "is"
        }
      ]
    }
  ],
  "start": "20230101",
  "end": "20230131",
  "metric": "uniques",
  "interval": "day"
}
```

### 2. segment_events

Advanced event segmentation with filters, metrics, and breakdowns.

**Parameters:**

- All parameters from `query_events`
- `filters` (array, optional): Additional filters for segmentation
  - `type` (string): Filter type (property, event, user)
  - `propertyName` (string, optional): Name of the property
  - `value` (mixed, optional): Value to filter by
  - `op` (string, optional): Operator for comparison
- `breakdowns` (array, optional): Breakdown dimensions
  - `type` (string): Breakdown type (event, user)
  - `propertyName` (string): Name of the property to break down by

**Example:**

```json
{
  "events": [
    {
      "eventType": "purchase"
    }
  ],
  "start": "20230101",
  "end": "20230131",
  "metric": "totals",
  "interval": "week",
  "filters": [
    {
      "type": "user",
      "propertyName": "country",
      "value": "US",
      "op": "is"
    }
  ],
  "breakdowns": [
    {
      "type": "user",
      "propertyName": "device_type"
    }
  ]
}
```

### 3. funnel_analysis

Analyze conversion funnels between sequential events.

**Parameters:**

- `events` (array): Array of at least 2 events in funnel sequence
  - `eventType` (string): Type of event
  - `propertyFilters` (array, optional): Filters for event properties
- `start` (string): Start date in YYYYMMDD format
- `end` (string): End date in YYYYMMDD format
- `mode` (string, optional): Funnel mode (ordered, unordered)
- `conversionWindow` (number, optional): Conversion window in milliseconds

**Example:**

```json
{
  "events": [
    {
      "eventType": "sign_up"
    },
    {
      "eventType": "complete_profile"
    },
    {
      "eventType": "first_purchase"
    }
  ],
  "start": "20230101",
  "end": "20230131",
  "mode": "ordered",
  "conversionWindow": 86400000
}
```

### 4. retention_analysis

Track user retention between starting and returning events.

**Parameters:**

- `startingEvent` (object): Starting event definition
  - `eventType` (string): Type of event
  - `propertyFilters` (array, optional): Filters for event properties
- `returningEvent` (object): Returning event definition
  - `eventType` (string): Type of event
  - `propertyFilters` (array, optional): Filters for event properties
- `start` (string): Start date in YYYYMMDD format
- `end` (string): End date in YYYYMMDD format
- `retentionType` (string, optional): Retention type (bracket, rolling)
- `returningInterval` (number, optional): Returning interval in days

**Example:**

```json
{
  "startingEvent": {
    "eventType": "sign_up"
  },
  "returningEvent": {
    "eventType": "user_login"
  },
  "start": "20230101",
  "end": "20230131",
  "retentionType": "rolling",
  "returningInterval": 7
}
```

### 5. user_activity

Retrieve detailed activity history for a specific user.

**Parameters:**

- `userId` (string): User ID to look up
- `offset` (number, optional): Offset for pagination
- `limit` (number, optional): Number of events to return (max 1000)

**Example:**

```json
{
  "userId": "user123",
  "limit": 100,
  "offset": 0
}
```

## Available Resources

### amplitude_events

Access event data for a specific event type and date range.

**URI Format:**
```
amplitude://events/{eventType}/{start}/{end}
```

**Example:**
```
amplitude://events/user_login/20230101/20230131
```

## API Compatibility

This server implements the Amplitude Dashboard REST API v2, supporting:
- Event Segmentation endpoint
- Funnel Analysis endpoint
- Retention Analysis endpoint
- User Activity endpoint

The implementation properly handles:
- URL encoding of complex JSON parameters
- Correct authentication via Basic Auth
- Metric types and intervals
- Advanced filtering and grouping
- EU residency server support

## Development

### Publishing to GitHub Package Registry

To publish a new version:

1. First, authenticate with GitHub Package Registry (one-time setup):
```bash
npm login --registry=https://npm.pkg.github.com
# Username: YOUR_GITHUB_USERNAME  
# Password: YOUR_GITHUB_PERSONAL_ACCESS_TOKEN (needs write:packages scope)
```

2. Publish using the provided script:
```bash
./publish.sh
# Or use npm script:
npm run publish:github
```

### Project Structure

```
amplitude-mcp/
├── src/
│   ├── index.ts                  # Main entry point with MCP server setup
│   ├── services/
│   │   └── amplitude.service.ts  # Amplitude API service implementation
│   ├── resources/
│   │   └── events.ts             # Event data resources
│   ├── types/
│   │   └── amplitude.ts          # Amplitude API types
│   └── utils/
│       └── config.ts             # Configuration and credential handling
├── bin/
│   └── cli.js                    # CLI entry point
├── dist/                         # Compiled JavaScript files
├── package.json
└── tsconfig.json
```

## License

MIT