Servidor MCP de Langfuse

Servidor del Protocolo de Contexto de Modelo para la observabilidad de Langfuse. Consulta trazas, depura errores, analiza sesiones y gestiona prompts.

¿Por qué langfuse-mcp?

Comparación con el MCP oficial de Langfuse (a fecha de enero de 2026):

Este proyecto proporciona un kit de herramientas de observabilidad completo —trazas, observaciones, sesiones, excepciones, prompts, datasets, colas de anotación y puntuaciones— mientras que el MCP oficial se centra en la gestión de prompts.

Inicio rápido

Requiere uv (para uvx).

Obtén las credenciales en Langfuse Cloud → Settings → API Keys. Si es autoalojado, utiliza la URL de tu instancia para 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

Reinicia tu CLI y verifica con /mcp (Claude Code) o codex mcp list (Codex).

Herramientas (37 en total)

Actualizaciones de elementos de Dataset (Upsert)

Langfuse utiliza upsert para los elementos de los datasets. Para editar un elemento existente, llama a create_dataset_item con item_id. Si el ID existe, se actualiza; de lo contrario, se crea un nuevo elemento.

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

Habilidad (Skill)

Este proyecto incluye una habilidad con manuales de depuración.

Vía skills (recomendado):

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

Vía skild:

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

Instalación manual:

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

Intenta preguntar: "help me debug langfuse traces"

Consulta skills/langfuse/SKILL.md para ver la documentación completa.

Carga selectiva de herramientas

Carga solo los grupos de herramientas que necesites para reducir el consumo de tokens:

langfuse-mcp --tools traces,prompts

Grupos disponibles: traces, observations, sessions, exceptions, prompts, datasets, annotation_queues, scores, schema

Modo de solo lectura

Deshabilita todas las operaciones de escritura para un acceso de solo lectura más seguro:

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

Esto deshabilita: 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

Otros clientes

Cursor

Crea .cursor/mcp.json en tu proyecto (o ~/.cursor/mcp.json para 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

Desarrollo

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

Licencia

MIT