langfuse-mcp

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 [email protected]."
• "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 [email protected] 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.

License

MIT © Hugoles.