hugoles/langfuse-mcp

npm version npm downloads CI Node License: MIT

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.