avivsinai/langfuse-mcp

**Usage:** 12,518 PyPI downloads last month (pypistats, 2026-08-19). v0.10.1.
Local MCP server and skill for Langfuse. Debug traces, sessions, and exceptions from Claude Code, Codex, Cursor, or any MCP client.
Why this instead of native Langfuse MCP?
Use this for local debug: first-class traces, sessions, and exceptions; route-decision tools; compact / file-dump output; plus the included langfuse skill.
Use official Langfuse MCP for hosted, zero-install access to the broader API (score writes, comments, models, media).
As of June 2026:
| | langfuse-mcp | Native Langfuse MCP |
|-|--------------|---------------------|
| **Primary fit** | Local debug: traces, sessions, exceptions | Hosted, zero-install API surface |
| **Deployment** | Local stdio or HTTP, via the Langfuse Python SDK | Native streamable HTTP at /api/public/mcp |
| **Trace / session / exception tools** | First-class | Observation/API-oriented access |
| **Route-decision tools** | Yes | No |
| **Token & output control** | Compact summaries, truncation, file-dump mode, tool-group gating | Hosted tool response + client |
| **Metrics & dataset runs** | Yes | Yes |
| **Prompt, dataset, queue & score reads** | Yes | Yes |
| **Score writes, comments, models, media** | No | Yes |
langfuse-mcp for local debug. Native MCP for hosted breadth.
See a failing trace in 2 minutes
Install is uvx langfuse-mcp plus Langfuse API keys — Quick Start for Claude Code, Codex, Cursor, or Docker.
After the client restarts, ask:
That maps to existing tools:
find_exceptions returns {group, count, observation_id, trace_id} (top 50 groups) — each group carries a representative observation/trace ID, and find_exceptions_in_file also yields full error records. Then optionally:
The exception tools detect errors by observation level == "ERROR" (strict; a non-empty status_message alone does not count). Counts describe error-level observations, not individual exception events — get_error_count returns exception_count: null for that reason. Exception details come from recorded metadata (exception.type / exception.message / exception.stacktrace, top-level or under metadata.attributes); absent values are null. Results are not a point-in-time snapshot.
Project Links
- Quick Start
- Agent Skill
- Tools
- Selective Tool Loading
- Read-Only Mode
- Other Clients
Quick Start
Requires uv (for uvx) and Python 3.10 or newer. CI verifies Python 3.10 through 3.14.
Get credentials from Langfuse Cloud → Settings → API Keys. If self-hosted, use your instance URL for LANGFUSE_HOST.
To pin a CI-verified interpreter explicitly, add --python 3.14 before langfuse-mcp.
Restart your CLI, then verify with /mcp (Claude Code) or codex mcp list (Codex).
Agent Skill
This repo ships a first-party langfuse skill for Claude Code and Codex. The skill gives agents concrete playbooks for trace debugging, exception triage, latency analysis, prompt management, and dataset work.
Install it when you want the agent to know when to reach for Langfuse and which MCP tools to call first.
**Via skills** (recommended):
**Via skild**:
**Manual install:**
After installing the skill, try:
The MCP server provides the tools; the skill provides the agent-facing workflow. See skills/langfuse/SKILL.md, skills/langfuse/references/setup.md, and skills/langfuse/references/tool-reference.md.
Tools (48 total)
| Category | Tools |
|----------|-------|
| Traces | fetch_traces, fetch_trace |
| Observations | fetch_observations, fetch_observation |
| Routing | find_route_decisions, get_route_decision, summarize_route_decisions, find_low_confidence_route_decisions |
| Sessions | fetch_sessions, get_session_details, get_user_sessions |
| Exceptions | find_exceptions, find_exceptions_in_file, get_exception_details, get_error_count |