OpenReplay

OpenReplay MCP Server provides AI-powered analytics by letting large language models query and analyze OpenReplay sessions through MCP-compatible endpoints. It supports both remote API access and a local, runtime-based server process to suit different deployment needs.

How to use

Connect to the OpenReplay MCP server from your MCP client either via the remote HTTP endpoint or by running the local MCP process. Both methods expose tools you can call to search, analyze, and report on session data. Start with the HTTP endpoint to access the API directly, or run the local process to host the MCP server on your machine and configure it with your OpenReplay credentials.

How to install

Prerequisites: ensure you have Node.js and npm installed on your system.

npm install
npm run build

Configuration and usage notes

Configure authentication and access in two ways. API Key authentication provides limited access to a subset of features. For full functionality, JWT-based authentication is required in your environment.

1. API Key authentication (current): you can list projects, fetch user sessions by user ID, retrieve session events, and view user details.

2. JWT authentication (future): enables complete session search with filters, performance metrics, funnel analysis, error tracking, and custom dashboards.

OpenReplay MCP configuration options

You can configure the server using environment variables. Create a file named .env by copying the example, then provide your OpenReplay credentials.

cp .env.example .env

OPENREPLAY_API_URL=https://api.openreplay.com
OPENREPLAY_API_KEY=your_organization_api_key
OPENREPLAY_PROJECT_KEY=your_project_key

Usage with Claude Desktop

If you use Claude Desktop, add a server entry that runs the MCP locally and passes your OpenReplay credentials as environment variables.

{
  "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 connection methods

Two MCP connection options are described here. You can use the HTTP endpoint for remote access or run the local MCP process via standard input/output (stdio). Each method exposes the same set of analysis tools through your MCP client.

Security notes

Keep your API key and project key secure. Do not expose credentials in client-side configurations or public repositories. If you plan to enable JWT-based access in the future, follow your security team's guidelines for token management and rotation.

Troubleshooting tips

If you encounter authentication errors, verify that OPENREPLAY_API_URL, OPENREPLAY_API_KEY, and OPENREPLAY_PROJECT_KEY are correctly set in the environment or in your .env file. For local runs, ensure the runtime path to the MCP index file is correct in your CLI or Claude Desktop configuration.

Available tools

search_sessions

Search and filter sessions with criteria such as date ranges, user properties, errors, and performance metrics.

get_session_details

Retrieve detailed information about a specific session, including all events, errors, network requests, and console logs.

get_session_events

Fetch all events from a session with optional filtering by event type.

aggregate_sessions

Aggregate session data across metrics like count, duration, error rate, and bounce rate.

get_user_journey

Trace the complete journey of a user across multiple sessions.

get_errors_issues

Identify errors and issues with impact and affected sessions.

get_funnel_analysis

Analyze funnels and conversion paths using custom step definitions.

get_performance_metrics

Obtain performance metrics such as page load times, LCP, TTI with percentiles.

execute_custom_query

Run advanced queries (SQL-like syntax for ClickHouse) for custom analysis.