Langfuse MCP Server
Model Context Protocol server for Langfuse observability. Query traces, debug errors, analyze sessions, manage prompts.
Why langfuse-mcp?
Comparison with official Langfuse MCP (as of Jan 2026):
| langfuse-mcp | Official | |
|---|---|---|
| Traces & Observations | Yes | No |
| Sessions & Users | Yes | No |
| Exception Tracking | Yes | No |
| Prompt Management | Yes | Yes |
| Selective Tool Loading | Yes | No |
This project provides a full observability toolkit — traces, observations, sessions, exceptions, and prompts — while the official MCP focuses on prompt management.
Quick Start
Requires uv (for uvx).
Get credentials from Langfuse Cloud → Settings → API Keys. If self-hosted, use your instance URL for LANGFUSE_HOST.
# Claude Code (project-scoped, shared via .mcp.json)
claude mcp add \
--scope project \
--env LANGFUSE_PUBLIC_KEY=pk-... \
--env LANGFUSE_SECRET_KEY=sk-... \
--env LANGFUSE_HOST=https://cloud.langfuse.com \
langfuse -- uvx --python 3.11 langfuse-mcp
# Codex CLI (user-scoped, stored in ~/.codex/config.toml)
codex mcp add langfuse \
--env LANGFUSE_PUBLIC_KEY=pk-... \
--env LANGFUSE_SECRET_KEY=sk-... \
--env LANGFUSE_HOST=https://cloud.langfuse.com \
-- uvx --python 3.11 langfuse-mcp
Restart your CLI, then verify with /mcp (Claude Code) or codex mcp list (Codex).
Tools (18 total)
| Category | Tools |
|---|---|
| Traces | fetch_traces, fetch_trace |
| Observations | fetch_observations, fetch_observation |
| Sessions | fetch_sessions, get_session_details, get_user_sessions |
| Exceptions | find_exceptions, find_exceptions_in_file, get_exception_details, get_error_count |
| Prompts | list_prompts, get_prompt, get_prompt_unresolved, create_text_prompt, create_chat_prompt, update_prompt_labels |
| Schema | get_data_schema |
Skill
This project includes a skill with debugging playbooks.
Claude Code:
/plugin marketplace add avivsinai/skills-marketplace
/plugin install langfuse@avivsinai-marketplace
Codex CLI:
$skill-installer install https://github.com/avivsinai/langfuse-mcp/tree/main/skills/langfuse
Then restart Codex.
Manual install (both):
cp -r skills/langfuse ~/.claude/skills/ # Claude Code
cp -r skills/langfuse ~/.codex/skills/ # Codex CLI
Try asking: "help me debug langfuse traces"
See skills/langfuse/SKILL.md for full documentation.
Selective Tool Loading
Load only the tool groups you need to reduce token overhead:
langfuse-mcp --tools traces,prompts
Available groups: traces, observations, sessions, exceptions, prompts, schema
Other Clients
Cursor
Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for global):
{
"mcpServers": {
"langfuse": {
"command": "uvx",
"args": ["--python", "3.11", "langfuse-mcp"],
"env": {
"LANGFUSE_PUBLIC_KEY": "pk-...",
"LANGFUSE_SECRET_KEY": "sk-...",
"LANGFUSE_HOST": "https://cloud.langfuse.com"
}
}
}
}
Docker
docker run --rm -i \
-e LANGFUSE_PUBLIC_KEY=pk-... \
-e LANGFUSE_SECRET_KEY=sk-... \
-e LANGFUSE_HOST=https://cloud.langfuse.com \
ghcr.io/avivsinai/langfuse-mcp:latest
Development
uv venv --python 3.11 .venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest
License
MIT