langfuse-mcp

# langfuse-mcp [](https://www.npmjs.com/package/langfuse-mcp) [](https://www.npmjs.com/package/langfuse-mcp) [](https://github.com/hugoles/langfuse-mcp/actions/workflows/ci.yml) [](https://nodejs.org) [](LICENSE) An [MCP](https://modelcontextprotocol.io) server that exposes the [Langfuse](https://langfuse.com) REST API as tools, so Claude (or any MCP client) can query your traces, observations, sessions, scores, prompts, datasets, and metrics during a conversation. Useful when you want to ask things like: - _"Why did trace `abc123` fail? Walk me through its observations."_ - _"List the 5 most recent traces with `level=ERROR` for user `alice@x.com`."_ - _"Summarize today's generation cost broken down by model."_ - _"Show me the production version of prompt `customer-support-v2`."_ …without leaving your assistant. ## Requirements - **Node.js 20 or newer** (`node --version`). - A Langfuse project with API keys ([cloud.langfuse.com → Settings → API Keys](https://cloud.langfuse.com/project/settings) on EU cloud, [us.cloud.langfuse.com](https://us.cloud.langfuse.com) on US cloud, or your self-hosted instance). ## Tools All tools are read-only and call the [Langfuse Public API](https://api.reference.langfuse.com) over HTTPS using your project keys for Basic Auth. ### Traces & observations | Tool | Description | | ------------------ | --------------------------------------------------------------- | | `listTraces` | List traces with filters. Returns summary metadata. | | `getTrace` | Fetch a single trace by id including the full observation tree. | | `listObservations` | List spans, generations, and events with filters. | | `getObservation` | Fetch a single observation by id. | ### Sessions | Tool | Description | | -------------- | -------------------------------------------- | | `listSessions` | List sessions within a time range. | | `getSession` | Fetch a session by id, including its traces. | ### Scores | Tool | Description | | ------------------ | ------------------------------------------------------------ | | `listScores` | List scores with filters. | | `getScore` | Fetch a single score by id. | | `listScoreConfigs` | List score configurations (definitions, ranges, categories). | | `getScoreConfig` | Fetch a score configuration by id. | ### Prompts | Tool | Description | | ------------- | ------------------------------------------------------------------------- | | `listPrompts` | List prompt definitions, optionally filtered by name, label, or tag. | | `getPrompt` | Fetch a prompt by name, optionally pinned to a specific version or label. | ### Datasets | Tool | Description | | ------------------ | ------------------------------------------------------------- | | `listDatasets` | List datasets configured in Langfuse. | | `getDataset` | Fetch a dataset by name. | | `listDatasetItems` | List items in a dataset (inputs, expected outputs, metadata). | | `getDatasetItem` | Fetch a single dataset item by id. | | `listDatasetRuns` | List evaluation runs for a dataset. | | `getDatasetRun` | Fetch a specific dataset run by name. | ### Metrics, models & misc | Tool | Description | | ----------------- | ------------------------------------------------------------------------------------------ | | `getMetrics` | Run a custom metrics query (counts, latency, cost, token usage). Pass a JSON query string. | | `getDailyMetrics` | Daily aggregated usage / cost / count metrics. | | `listModels` | List models known to Langfuse (for cost / token attribution). | | `getModel` | Fetch a model definition by id. | | `listProjects` | List projects accessible to the current API key. | | `listComments` | List comments attached to traces, observations, sessions, or prompts. | | `getComment` | Fetch a single comment by id. | | `getMedia` | Fetch metadata for a media attachment (image, audio, file). | | `getHealth` | Ping the Langfuse public health endpoint — useful for credential validation. | ## Install Zero install with `npx`: ```bash npx -y langfuse-mcp ``` Or install globally: ```bash npm i -g langfuse-mcp langfuse-mcp --version ``` ## Configuration The server reads three environment variables: | Variable | Required | Description | | --------------------- | -------- | ------------------------------------------------------------------------------------------------------- | | `LANGFUSE_PUBLIC_KEY` | yes | Project public key (`pk-lf-…`). | | `LANGFUSE_SECRET_KEY` | yes | Project secret key (`sk-lf-…`). | | `LANGFUSE_BASE_URL` | yes | e.g. `https://cloud.langfuse.com` (EU) or `https://us.cloud.langfuse.com` (US) or your self-hosted URL. | | `LANGFUSE_ENV_FILE` | no | Optional path to a `.env` file to load instead of `./.env`. | > **Where do I get my keys?** In the Langfuse UI: **Settings → API Keys → Create new API keys**. Keys are scoped to a single project and a single region (EU vs US are separate accounts — match your `LANGFUSE_BASE_URL` to the region you created the keys in). If a `.env` file exists in the working directory it will be loaded automatically. See [`.env.example`](.env.example) for a starter file. ## Use with Claude Desktop Edit `claude_desktop_config.json`: - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` - **Linux:** `~/.config/Claude/claude_desktop_config.json` ```json { "mcpServers": { "langfuse": { "command": "npx", "args": ["-y", "langfuse-mcp"], "env": { "LANGFUSE_PUBLIC_KEY": "pk-lf-…", "LANGFUSE_SECRET_KEY": "sk-lf-…", "LANGFUSE_BASE_URL": "https://cloud.langfuse.com" } } } } ``` Restart Claude Desktop after editing. The MCP server icon should appear in the chat input. ## Use with Claude Code Project-level (`./.mcp.json`): ```json { "mcpServers": { "langfuse": { "command": "npx", "args": ["-y", "langfuse-mcp"], "env": { "LANGFUSE_PUBLIC_KEY": "pk-lf-…", "LANGFUSE_SECRET_KEY": "sk-lf-…", "LANGFUSE_BASE_URL": "https://cloud.langfuse.com" } } } } ``` User-level config lives at `~/.claude.json` and uses the same shape. ## Use with Cursor Project-level: `.cursor/mcp.json`. User-level: `~/.cursor/mcp.json`. ```json { "mcpServers": { "langfuse": { "command": "npx", "args": ["-y", "langfuse-mcp"], "env": { "LANGFUSE_PUBLIC_KEY": "pk-lf-…", "LANGFUSE_SECRET_KEY": "sk-lf-…", "LANGFUSE_BASE_URL": "https://cloud.langfuse.com" } } } } ``` ## Use with Cline (VS Code) In VS Code settings (`settings.json`): ```json { "cline.mcpServers": { "langfuse": { "command": "npx", "args": ["-y", "langfuse-mcp"], "env": { "LANGFUSE_PUBLIC_KEY": "pk-lf-…", "LANGFUSE_SECRET_KEY": "sk-lf-…", "LANGFUSE_BASE_URL": "https://cloud.langfuse.com" } } } } ``` ## Use with Continue In `~/.continue/config.json`: ```json { "mcpServers": [ { "name": "langfuse", "command": "npx", "args": ["-y", "langfuse-mcp"], "env": { "LANGFUSE_PUBLIC_KEY": "pk-lf-…", "LANGFUSE_SECRET_KEY": "sk-lf-…", "LANGFUSE_BASE_URL": "https://cloud.langfuse.com" } } ] } ``` ## Use with Windsurf In Windsurf's MCP settings, add: ```json { "mcpServers": { "langfuse": { "command": "npx", "args": ["-y", "langfuse-mcp"], "env": { "LANGFUSE_PUBLIC_KEY": "pk-lf-…", "LANGFUSE_SECRET_KEY": "sk-lf-…", "LANGFUSE_BASE_URL": "https://cloud.langfuse.com" } } } } ``` ## Use with any other MCP client The server speaks MCP over stdio. Any MCP client can launch it as a subprocess: ```bash LANGFUSE_PUBLIC_KEY=pk-lf-… \ LANGFUSE_SECRET_KEY=sk-lf-… \ LANGFUSE_BASE_URL=https://cloud.langfuse.com \ npx -y langfuse-mcp ``` ## Try it Once wired up, ask your assistant things like: - _"Use the `getHealth` tool to confirm langfuse-mcp is connected."_ - _"List the 5 most recent traces with `level=ERROR`."_ - _"Show me trace `abc123` with all its observations."_ - _"What scores did user `alice@example.com` receive this week?"_ - _"Get the production version of prompt `customer-support`."_ - _"List dataset runs for `eval-2026-q1` and tell me which one had the highest accuracy score."_ ## Troubleshooting **`401 Unauthorized` on the first call** - Wrong region: Langfuse Cloud EU and US are separate accounts. Make sure `LANGFUSE_BASE_URL` matches the region where you created the keys (`https://cloud.langfuse.com` for EU, `https://us.cloud.langfuse.com` for US). - Quoted keys in `.env`: this server strips surrounding quotes, but a stray space can still break Basic Auth. Re-paste the key. - Use `getHealth` first to confirm credentials before running other tools. **`npx` keeps using an old version** ```bash npx -y langfuse-mcp@latest ``` `npx` caches packages aggressively. The `@latest` suffix forces a refresh. **`LANGFUSE_BASE_URL must be a full URL` error** The most common cause is a missing scheme. Use `https://cloud.langfuse.com`, not `cloud.langfuse.com`. **Self-hosted Langfuse** Use the full base URL of your deployment without a trailing slash or path. Example: `https://langfuse.mycompany.internal`. The server normalizes a single trailing slash, but anything else (`/api`, `/public`) will break path joining. **MCP server icon doesn't appear in Claude Desktop** - Check the Claude Desktop log: `~/Library/Logs/Claude/mcp*.log` (macOS) or `%APPDATA%\Claude\Logs\` (Windows). The server writes a `langfuse-mcp v… connected` line to stderr on success. - Make sure Node 20+ is on your PATH (Claude Desktop uses your login shell PATH). - Quit Claude Desktop fully (not just close the window) and relaunch. **Cryptic `ERR_REQUIRE_ESM` / `Unexpected token` on startup** Your Node version is too old. This package requires Node ≥ 20. Run `node --version` and upgrade if needed (e.g. via [nvm](https://github.com/nvm-sh/nvm)). ## Development ```bash git clone https://github.com/hugoles/langfuse-mcp.git cd langfuse-mcp npm install cp .env.example .env # macOS/Linux copy .env.example .env # Windows cmd npm run dev # tsx src/index.ts (no build step) ``` Other scripts: | Script | What it does | | ----------------------------------------- | ------------------------------ | | `npm run build` | Compile TypeScript to `dist/`. | | `npm start` | Run the built server. | | `npm run typecheck` | `tsc --noEmit`. | | `npm run lint` | ESLint. | | `npm run format` / `npm run format:check` | Prettier write / check. | | `npm test` | Vitest. | ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and PRs are welcome — please run `npm run typecheck && npm run lint && npm test` locally before opening one. ## Security Found a vulnerability? Please report it privately as described in [SECURITY.md](SECURITY.md). Do not open a public issue. ## License [MIT](LICENSE) © Hugoles.