The langfuse-mcp server provides a comprehensive observability and management toolkit for Langfuse through the Model Context Protocol, enabling you to query, debug, and manage AI application data.
Core Capabilities:
Trace & Observation Analysis: Fetch and filter traces by age, name, user ID, session ID, tags, and metadata; query observations by type (SPAN, GENERATION, EVENT), name, and associated IDs; retrieve detailed information with flexible output formats (compact, full JSON string, or file)
Session & User Tracking: List sessions within time ranges, get detailed session information with optional full observation data, and retrieve all sessions for specific users
Exception & Error Tracking: Find exceptions grouped by file, function, or type; get detailed exception information for specific files or traces; count traces with errors over time periods
Prompt Management: List and filter prompts by name, label, or tag; fetch prompts with or without resolved dependencies; create new text and chat prompt versions; update labels across versions
Dataset Management: List, create, and manage datasets for evaluation test cases; create/update dataset items with upsert functionality; delete items; filter by source trace or observation ID
Schema Access: Retrieve detailed schema definitions for Langfuse data structures including traces, spans, and events
Configuration & Control: Selective tool loading to reduce token overhead, read-only mode for safe exploration, pagination support across all list operations, and compatibility with Claude Code, Codex CLI, Cursor, and Docker
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 |
Dataset Management | Yes | No |
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.
Restart your CLI, then verify with /mcp (Claude Code) or codex mcp list (Codex).
Tools (25 total)
Category | Tools |
Traces |
|
Observations |
|
Sessions |
|
Exceptions |
|
Prompts |
|
Datasets |
|
Schema |
|
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.
Skill
This project includes a skill with debugging playbooks.
Via (recommended):
Via :
Manual install:
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:
Available groups: traces, observations, sessions, exceptions, prompts, datasets, schema
Read-Only Mode
Disable all write operations for safer read-only access:
This disables: create_text_prompt, create_chat_prompt, update_prompt_labels, create_dataset, create_dataset_item, delete_dataset_item
Other Clients
Cursor
Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for global):
Docker
Development
License
MIT