Langfuse MCP-Server

Model Context Protocol-Server für Langfuse-Observability. Traces abfragen, Fehler debuggen, Sessions analysieren, Prompts verwalten.

Warum langfuse-mcp?

Vergleich mit dem offiziellen Langfuse MCP (Stand Januar 2026):

Dieses Projekt bietet ein vollständiges Observability-Toolkit – Traces, Observations, Sessions, Exceptions, Prompts, Datasets, Annotation-Queues und Scores –, während sich das offizielle MCP auf die Prompt-Verwaltung konzentriert.

Schnelleinstieg

Erfordert uv (für uvx).

Erhalten Sie Ihre Zugangsdaten von Langfuse Cloud → Settings → API Keys. Bei einer Self-Hosted-Instanz verwenden Sie Ihre Instanz-URL für 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 --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

Starten Sie Ihr CLI neu und überprüfen Sie die Installation mit /mcp (Claude Code) oder codex mcp list (Codex).

Tools (insgesamt 37)

Dataset-Item-Updates (Upsert)

Langfuse verwendet Upsert für Dataset-Items. Um ein bestehendes Item zu bearbeiten, rufen Sie create_dataset_item mit item_id auf. Wenn die ID existiert, wird sie aktualisiert; andernfalls wird ein neues Item erstellt.

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

Skill

Dieses Projekt enthält einen Skill mit Debugging-Playbooks.

Via skills (empfohlen):

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

Via skild:

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

Manuelle Installation:

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

Versuchen Sie es mit der Frage: "help me debug langfuse traces"

Siehe skills/langfuse/SKILL.md für die vollständige Dokumentation.

Selektives Laden von Tools

Laden Sie nur die Tool-Gruppen, die Sie benötigen, um den Token-Overhead zu reduzieren:

langfuse-mcp --tools traces,prompts

Verfügbare Gruppen: traces, observations, sessions, exceptions, prompts, datasets, annotation_queues, scores, schema

Read-Only-Modus

Deaktivieren Sie alle Schreibvorgänge für einen sichereren schreibgeschützten Zugriff:

langfuse-mcp --read-only
# Or via environment variable
LANGFUSE_MCP_READ_ONLY=true langfuse-mcp

Dies deaktiviert: create_text_prompt, create_chat_prompt, update_prompt_labels, create_dataset, create_dataset_item, delete_dataset_item, create_annotation_queue, create_annotation_queue_item, update_annotation_queue_item, delete_annotation_queue_item, create_annotation_queue_assignment, delete_annotation_queue_assignment

Andere Clients

Cursor

Erstellen Sie .cursor/mcp.json in Ihrem Projekt (oder ~/.cursor/mcp.json für 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

Entwicklung

uv venv --python 3.11 .venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest

Lizenz

MIT