Langfuse MCP

Community Data and databases

Read access to the Langfuse Public API: traces, observations, sessions, scores, prompts, datasets, metrics, models, projects and comments.

Source code Documentation

Install

The installation steps are in the documentation below. Documentation

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents

langfuse-mcp
Requirements
Tools
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

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

License

MIT © Hugoles.

Frequently asked questions

What is Langfuse MCP?

Read access to the Langfuse Public API: traces, observations, sessions, scores, prompts, datasets, metrics, models, projects and comments.

How do I install Langfuse MCP?

Follow the installation steps in its documentation, shown on this page and in its repository.

Is Langfuse MCP open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains Langfuse MCP?

It is published by hugoles. AI.tn lists it but does not maintain or endorse it.

From the community awesome-mcp-servers lists and the project's GitHub repository. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.

Server details

Listed in: Community lists (awesome-mcp-servers)
Publisher: hugoles
Category: Data and databases
Runs: Local
GitHub stars: ★ 1
License: MIT
Language: TypeScript
Last commit: Jun 15, 2026
Open issues: 8

github.com/hugoles/langfuse-mcp

Similar servers

RowAttest Runs an eight-stage isolation test against your staging Supabase and issues a signed at...
codeDB Lens Read-only health checks and data questions for SQL Server and PostgreSQL, with your sav...
FastrMemory Local-first cognitive agent memory with bi-temporal SQLite, replayable history, hybrid ...
Sezzlee Excel Read spreadsheets; build immutable reports with bulk preparation, calculation, charts a...
TeamOnly Deploy AI-built internal apps behind your company login, with a database, files and sec...
WaveHouse Cloud Browse, query, and administer your managed WaveHouse + ClickHouse projects (schema, pip...
Open data: clinical trials, EU tenders, companies, fuel prices Official open data as JSON: clinical trials, EU tenders, papers, apps, French firms, fu...
frugal-memory Memory for AI assistants in one SQLite file: full-text search, no vectors, no embeddings.

Data and databases