langfuse-mcp

![npm version](https://www.npmjs.com/package/langfuse-mcp) ![npm downloads](https://www.npmjs.com/package/langfuse-mcp) ![CI](https://github.com/hugoles/langfuse-mcp/actions/workflows/ci.yml) ![Node](https://nodejs.org) ![License: MIT](LICENSE)

An MCP server that exposes the Langfuse 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 on EU cloud, us.cloud.langfuse.com on US cloud, or your self-hosted instance).

Tools

All tools are read-only and call the Langfuse Public API 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:

npx -y langfuse-mcp

Or install globally:

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 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

{
  "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):

{
  "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.

{
  "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):

{
  "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:

{
  "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:

{
  "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:

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

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).

Development

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. 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. Do not open a public issue.

langfuse-mcp

langfuse-mcp

Requirements

Tools

Traces & observations

Sessions

Scores

Prompts

Datasets

Metrics, models & misc

Install

Configuration

Use with Claude Desktop

Use with Claude Code

Use with Cursor

Use with Cline (VS Code)

Use with Continue

Use with Windsurf

Use with any other MCP client

Try it

Troubleshooting

Development

Contributing

Security

License

Score

Proud of your score? Add this badge to your README.

langfuse-mcp FAQ

How do I install langfuse-mcp?

Is langfuse-mcp an official MCP server?

Related MCP servers

Related guides