Langfuse MCP Server

PyPI Downloads Python 3.10–3.13 License: MIT

Сервер Model Context Protocol для наблюдаемости Langfuse. Запрашивайте трассировки, отлаживайте ошибки, анализируйте сессии, управляйте промптами.

Почему langfuse-mcp?

Сравнение с официальным Langfuse MCP (по состоянию на январь 2026 г.):

	langfuse-mcp	Официальный
Трассировки и наблюдения	Да	Нет
Сессии и пользователи	Да	Нет
Отслеживание исключений	Да	Нет
Управление промптами	Да	Да
Управление наборами данных	Да	Нет
Очереди аннотаций	Да	Нет
Оценки (v2)	Да	Нет
Выборочная загрузка инструментов	Да	Нет

Этот проект предоставляет полный набор инструментов для наблюдаемости — трассировки, наблюдения, сессии, исключения, промпты, наборы данных, очереди аннотаций и оценки, — в то время как официальный MCP фокусируется на управлении промптами.

Быстрый старт

Требуется uv (для uvx).

Получите учетные данные в Langfuse Cloud → Settings → API Keys. Если используете self-hosted версию, укажите URL вашего экземпляра в 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

Перезапустите CLI, затем проверьте работу с помощью /mcp (Claude Code) или codex mcp list (Codex).

Инструменты (всего 37)

Категория	Инструменты
Трассировки	`fetch_traces`, `fetch_trace`
Наблюдения	`fetch_observations`, `fetch_observation`
Сессии	`fetch_sessions`, `get_session_details`, `get_user_sessions`
Исключения	`find_exceptions`, `find_exceptions_in_file`, `get_exception_details`, `get_error_count`
Промпты	`list_prompts`, `get_prompt`, `get_prompt_unresolved`, `create_text_prompt`, `create_chat_prompt`, `update_prompt_labels`
Наборы данных	`list_datasets`, `get_dataset`, `list_dataset_items`, `get_dataset_item`, `create_dataset`, `create_dataset_item`, `delete_dataset_item`
Очереди аннотаций	`list_annotation_queues`, `create_annotation_queue`, `get_annotation_queue`, `list_annotation_queue_items`, `get_annotation_queue_item`, `create_annotation_queue_item`, `update_annotation_queue_item`, `delete_annotation_queue_item`, `create_annotation_queue_assignment`, `delete_annotation_queue_assignment`
Оценки	`list_scores_v2`, `get_score_v2`
Схема	`get_data_schema`

Обновление элементов набора данных (Upsert)

Langfuse использует upsert для элементов набора данных. Чтобы отредактировать существующий элемент, вызовите create_dataset_item с параметром item_id. Если ID существует, он обновится; в противном случае будет создан новый элемент.

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

Навык (Skill)

Этот проект включает навык с руководствами по отладке.

Через skills (рекомендуется):

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

Через skild:

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

Ручная установка:

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

Попробуйте спросить: "help me debug langfuse traces"

Полную документацию см. в skills/langfuse/SKILL.md.

Выборочная загрузка инструментов

Загружайте только те группы инструментов, которые вам нужны, чтобы уменьшить нагрузку на токены:

langfuse-mcp --tools traces,prompts

Доступные группы: traces, observations, sessions, exceptions, prompts, datasets, annotation_queues, scores, schema

Режим только для чтения

Отключите все операции записи для более безопасного доступа в режиме только для чтения:

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

Это отключает: 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

Другие клиенты

Cursor

Создайте .cursor/mcp.json в вашем проекте (или ~/.cursor/mcp.json для глобального использования):

{
  "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

Разработка

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

Лицензия

MIT

langfuse-mcp