mcp -guide

A guide on how to use the Amplitude MCP server

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

Command

claude mcp add --transport stdio amplitude-mcp-server-guide npx -y amplitude-mcp-server \
  --env OAUTH_SCOPE="amplitude.api" \
  --env OAUTH_CLIENT_ID="your-client-id" \
  --env AMPLITUDE_REGION="us or eu (default: us)" \
  --env OAUTH_CLIENT_SECRET="your-client-secret"

How to use

The Amplitude MCP Server provides a conversational interface to analyze Amplitude data. It exposes tools for analytics queries, content retrieval (charts, dashboards, notebooks), experiments, and user insights like session replays. After configuring OAuth and pointing your AI client to the correct region URL, you can ask the model to run natural language questions such as retrieving a specific chart, evaluating an experiment’s results, or fetching session replays that match criteria. The tools are organized into Core Analytics, Content Management, and User Insights, allowing you to perform end-to-end data exploration from natural language prompts.

To use it, add the MCP server to your AI client configuration, authenticate with OAuth, select the region-specific server URL, and begin with simple prompts like: “Show me the top events by volume this week” or “Retrieve the dashboard definition for the Revenue Overview chart.” You can then refine your questions with filters, time ranges, and specific projects or segments to drill down into the data without leaving your AI workspace.

How to install

Prerequisites

An Amplitude organization with appropriate permissions
A supported AI client (e.g., Claude, Cursor, ChatGPT)
Node.js installed if you plan to run via npx locally

Installation steps

Ensure you have Node.js and npm installed
- Check: node -v and npm -v
Set up OAuth credentials in your Amplitude account and note the client ID/secret
Start the MCP server using npm/npx as described in the mcp_config
- If using npx: npx -y amplitude-mcp-server
Configure your AI client to point to the correct region URL:
- US: https://mcp.amplitude.com/mcp
- EU: https://mcp.eu.amplitude.com/mcp
Authenticate when prompted by your AI client and start issuing natural language queries

Additional notes

Environment and configuration tips:

Ensure OAuth scopes align with Amplitude API permissions required for data access.
Use region-specific URLs to comply with data residency requirements.
If you encounter authentication failures, recheck клиент ID/secret and that the OAuth redirect URI is whitelisted in your Amplitude app settings.
Data access respects your Amplitude permissions; you’ll see results only for projects you can access in the Amplitude web interface.
When troubleshooting, start with simple prompts (e.g., fetch a single chart or a small dataset) before layering complex queries.
If the MCP server is in beta in your environment, expect ongoing updates; refer to the official Amplitude MCP docs for any breaking changes.