Langfuse MCP 服务器

PyPI Downloads Python 3.10–3.13 License: MIT

用于 Langfuse 可观测性的 Model Context Protocol 服务器。查询追踪、调试错误、分析会话、管理提示词。

为什么选择 langfuse-mcp？

与官方 Langfuse MCP 的对比（截至 2026 年 1 月）：

	langfuse-mcp	官方
追踪与观测 (Traces & Observations)	是	否
会话与用户 (Sessions & Users)	是	否
异常追踪 (Exception Tracking)	是	否
提示词管理 (Prompt Management)	是	是
数据集管理 (Dataset Management)	是	否
标注队列 (Annotation Queues)	是	否
评分 (Scores v2)	是	否
选择性工具加载 (Selective Tool Loading)	是	否

本项目提供了一个完整的可观测性工具包——包括追踪、观测、会话、异常、提示词、数据集、标注队列和评分——而官方 MCP 主要侧重于提示词管理。

快速开始

需要 uv (用于 uvx)。

从 Langfuse Cloud → Settings → API Keys 获取凭据。如果是自托管，请将 LANGFUSE_HOST 设置为您的实例 URL。

# 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（更新或插入）。要编辑现有条目，请使用 item_id 调用 create_dataset_item。如果 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 获取完整文档。

选择性工具加载

仅加载您需要的工具组以减少 Token 开销：

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

Install Server

A

security – no known vulnerabilities

A

license - permissive license

-

quality - not tested

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Related Servers

Tools

View all tools

langfuse-mcp