# OpenReplay MCP Server

An MCP (Model Context Protocol) server that provides AI-powered analytics for OpenReplay sessions. This server enables LLMs to query and analyze user sessions through OpenReplay's API.

## Authentication Methods

### API Key Authentication (Current)
The server currently uses API key authentication which provides access to:
- List all projects
- Get user sessions by user ID
- Get session events
- User details

**Note**: API key authentication has limited access. For full functionality (session search, metrics, funnels, etc.), JWT authentication is required.

### JWT Authentication (Future)
Full access to all OpenReplay features including:
- Complete session search with filters
- Performance metrics and analytics
- Funnel analysis
- Error tracking and aggregation
- Custom dashboards and metrics

## Installation

```bash
npm install
npm run build
```

## Configuration

1. Copy `.env.example` to `.env`:
```bash
cp .env.example .env
```

2. Configure your OpenReplay credentials:
```env
# OpenReplay API URL
# For cloud: https://api.openreplay.com (default)
# For self-hosted: Your instance URL
OPENREPLAY_API_URL=https://api.openreplay.com

# Organization API Key (find in Preferences > Account > Organization API Key)
OPENREPLAY_API_KEY=your_organization_api_key

# Project key from your project settings
OPENREPLAY_PROJECT_KEY=your_project_key
```

## Usage with Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "openreplay": {
      "command": "node",
      "args": ["/path/to/openreplay-mcp/dist/index.js"],
      "env": {
        "OPENREPLAY_API_URL": "https://api.openreplay.com",
        "OPENREPLAY_API_KEY": "your_organization_api_key",
        "OPENREPLAY_PROJECT_KEY": "your_project_key"
      }
    }
  }
}
```

## Available Tools

### search_sessions
Search and filter sessions with various criteria like date range, user properties, errors, performance metrics.

### get_session_details
Get detailed information about a specific session including all events, errors, network requests, console logs.

### get_session_events
Get all events from a session with optional filtering by event type.

### aggregate_sessions
Aggregate session data with various metrics and groupings (count, avg_duration, error_rate, bounce_rate, etc.).

### get_user_journey
Get the complete journey of a user across multiple sessions.

### get_errors_issues
Get errors and issues with their impact and affected sessions.

### get_funnel_analysis
Analyze user funnels and conversion paths with custom step definitions.

### get_performance_metrics
Get performance metrics like page load times, LCP, TTI with percentiles.

### execute_custom_query
Execute custom queries for advanced analysis (SQL-like syntax for ClickHouse).

## Example Queries

Once connected, you can ask the LLM questions like:

- "What are the most common drop-off points in our checkout flow?"
- "Show me the longest user sessions from the last week"
- "What JavaScript errors are affecting the most users?"
- "Analyze the user journey for users who converted vs those who didn't"
- "What pages have the worst performance metrics?"
- "Find patterns in sessions that resulted in errors"
- "Show me the bounce rate by device type and country"

## Development

```bash
# Run in development mode
npm run dev

# Build for production
npm run build

# Start production server
npm start
```

## License

MIT