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

Sessions

Scores

Prompts

Datasets

Metrics, models & misc

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:

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:

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.