Langfuse MCP

Langfuse MCP Server

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:

find exceptions in the last day

That maps to existing tools:

find_exceptions(age=1440, group_by="file")

find_exceptions_in_file(filepath=" ", age=1440) get_exception_details(trace_id=" ")

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:

fetch_trace(trace_id="<trace_id>", include_observations=true)

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.exception_count is the same error-observation total reported by find_exceptions.metadata.observation_count (including groups beyond the top 50). 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.

# Claude Code (project-scoped, shared via .mcp.json)

claude mcp add \ -e LANGFUSE_PUBLIC_KEY=pk-... \ -e LANGFUSE_SECRET_KEY=sk-... \ -e LANGFUSE_HOST=https://cloud.langfuse.com \ --scope project \ langfuse -- uvx 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 langfuse-mcp

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](https://github.com/vercel-labs/add-skill) (recommended):

npx skills add avivsinai/langfuse-mcp -g -y

Via [skild](https://skild.sh):

npx skild install @avivsinai/langfuse -t claude -y

Manual install:

cp -r skills/langfuse ~/.claude/skills/   # Claude Code

cp -r skills/langfuse ~/.codex/skills/ # Codex CLI

After installing the skill, try:

help me debug langfuse traces

find exceptions in the last day why was this user's session slow?

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)

On Observations API v2, traces are built from root observations. fetch_traces omits traces without a root observation, and fetch_trace cannot find traces with no observations.

Dataset-run reads use the experiments API when the installed Langfuse SDK exposes it (Python SDK 4.13.1+). The older routes remain a fallback for self-hosted servers that do not serve experiments. delete_dataset_run uses the legacy delete route while it works; after that route is removed, it deletes the run's traces only when you pass delete_traces=True. Trace deletion also removes observations and related scores. create_dataset_run_item still uses the legacy link API; when that API is gone, create experiment data through the SDK experiment runner or OTel ingestion.

Dataset Item Updates (Upsert)

Langfuse uses upsert for dataset items. To edit an existing item, call create_dataset_item with item_id. If the ID exists, it updates; otherwise it creates a new item.

create_dataset_item(dataset_name="qa-test-cases", item_id="item_123", input={"question": "What is 2+2?"}, expected_output={"answer": "4"})

Metrics Queries

query_metrics aggregates telemetry server-side (cost, latency, tokens, counts, score values) so agents can answer "what did inference cost?" or "what's p95 latency by model?" without pulling raw traces. Call get_metrics_schema for the full view/dimension/measure catalog.

query_metrics(

view="observations", metrics=[{"measure": "totalCost", "aggregation": "sum"}, {"measure": "latency", "aggregation": "p95"}], dimensions=["providedModelName"], age=1440, # last 24h; or pass from_timestamp / to_timestamp )

High-cardinality fields (id, traceId, userId, sessionId) must be used in filters, not dimensions. The v2 metrics endpoint is Langfuse Cloud-only; self-hosted instances may return 404.

Selective Tool Loading

Load only the tool groups you need to reduce token overhead:

langfuse-mcp --tools traces,prompts

Available groups: traces, observations, routing, sessions, exceptions, prompts, datasets, annotation_queues, scores, metrics, schema

The routing group is router-neutral. It reads Langfuse span observations with metadata.schema_version: "mcp.route_decision.v1" and filters on route-decision fields stored in observation metadata, such as decision_id, router_name, provider, and capability_id.

Read-Only Mode

Disable all write operations for safer read-only access:

langfuse-mcp --read-only

Or via environment variable

LANGFUSE_MCP_READ_ONLY=true langfuse-mcp

This disables: create_text_prompt, create_chat_prompt, update_prompt_labels, create_dataset, create_dataset_item, delete_dataset_item, create_dataset_run_item, delete_dataset_run, create_annotation_queue, create_annotation_queue_item, update_annotation_queue_item, delete_annotation_queue_item, create_annotation_queue_assignment, delete_annotation_queue_assignment

Default Output Mode

Set the MCP-exposed default output_mode so clients that omit the parameter automatically use your preferred mode:

langfuse-mcp --default-output-mode full_json_file

Or via environment variable

LANGFUSE_MCP_DEFAULT_OUTPUT_MODE=full_json_file langfuse-mcp

Supported values: compact, full_json_string, full_json_file

This updates the default shown in MCP tool schemas. Clients can still override it per call by passing output_mode explicitly.

Other Clients

Cursor

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for global):

{

"mcpServers": { "langfuse": { "command": "uvx", "args": ["langfuse-mcp"], "env": { "LANGFUSE_PUBLIC_KEY": "pk-...", "LANGFUSE_SECRET_KEY": "sk-...", "LANGFUSE_HOST": "https://cloud.langfuse.com", "LANGFUSE_MCP_DEFAULT_OUTPUT_MODE": "full_json_file" } } } }

Docker (single project)

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

Multiple projects with profiles (stdio)

For local clients (Claude Code, Codex, Cursor), keep the credentials of each Langfuse project in a profiles file and register one MCP server per project. Each server starts with --profile .

The file is TOML at $XDG_CONFIG_HOME/langfuse-mcp/profiles.toml (or `~/.config/langfuse-mc