Langfuse MCP (Model Context Protocol)

Langfuse MCP Server

用量：上月 PyPI 下载量为 12,518 次（pypistats，2026-08-19）。v0.10.1。

用于 Langfuse 的本地 MCP 服务和技能。可从 Claude Code、Codex、Cursor 或任何 MCP 客户端调试跟踪、会话和异常。

为什么不用 Langfuse 原生 MCP？

本地调试请使用此工具：一流的跟踪、会话和异常支持；路由决策工具；精简输出／文件转储输出；以及附带的 langfuse 技能。

如需托管式、免安装地访问更广泛的 API（写入评分、评论、模型、媒体），请使用官方的 Langfuse MCP。

截至 2026 年 6 月：

	langfuse-mcp	Native Langfuse MCP
主要用途	本地调试：跟踪、会话、异常	托管式、免安装的 API 接口
部署方式	通过 Langfuse Python SDK 使用本地 stdio 或 HTTP	/api/public/mcp 上的原生可流式 HTTP
跟踪／会话／异常工具	一流支持	面向 Observation／API 的访问
路由决策工具	是	否
令牌与输出控制	精简摘要、截断、文件转储模式、工具组门控	托管工具响应 + 客户端
指标与数据集运行	是	是
提示词、数据集、队列与评分读取	是	是
评分写入、评论、模型、媒体	否	是

本地调试请使用 langfuse-mcp。如需更广泛的托管功能，请使用原生 MCP。

2 分钟内查看失败的跟踪

安装只需运行 uvx langfuse-mcp 并配置 Langfuse API 密钥——Claude Code、Codex、Cursor 或 Docker 的安装步骤请参阅快速开始。

客户端重启后，询问：

find exceptions in the last day

这会映射到现有工具：

find_exceptions(age=1440, group_by="file")
find_exceptions_in_file(filepath="<file from the grouping>", age=1440)
get_exception_details(trace_id="<trace_id from the file results>")

find_exceptions 返回 {group, count, observation_id, trace_id}（前 50 个分组）——每个分组都包含一个代表性的 observation／trace ID；find_exceptions_in_file 还会返回完整的错误记录。然后可选执行：

fetch_trace(trace_id="<trace_id>", include_observations=true)

异常工具通过 observation 的 level == "ERROR" 检测错误（严格匹配；仅有非空的 status_message 不算）。计数表示错误级别的 observation 数量，而非单个异常事件数量——get_error_count.exception_count 与 find_exceptions.metadata.observation_count 报告的错误 observation 总数相同（包括前 50 个以外的分组）。异常详情来自已记录的元数据（exception.type／exception.message／exception.stacktrace，位于顶层或 metadata.attributes 下）；缺失值为 null。结果并非某个时间点的快照。

项目链接

• 快速开始
• Agent 技能
• 工具
• 选择性加载工具
• 只读模式
• 其他客户端

快速开始

需要安装 uv（用于运行 uvx）和 Python 3.10 或更高版本。CI 会验证 Python 3.10 至 3.14。

从 Langfuse Cloud → Settings → API Keys 获取凭据。如果是自托管部署，请将实例 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 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 langfuse-mcp

如需明确指定经过 CI 验证的解释器版本，请在 langfuse-mcp 前添加 --python 3.14。

重启命令行客户端，然后使用 /mcp（Claude Code）或 codex mcp list（Codex）进行验证。

Agent 技能

此仓库为 Claude Code 和 Codex 提供官方 langfuse 技能。该技能为 Agent 提供具体的操作指南，涵盖跟踪调试、异常分类、延迟分析、提示词管理和数据集处理。

如果你希望 Agent 知道何时使用 Langfuse，以及优先调用哪些 MCP 工具，请安装此技能。

通过 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
find exceptions in the last day
why was this user's session slow?

MCP 服务提供工具；技能提供面向 Agent 的工作流。请参阅 skills/langfuse/SKILL.md、skills/langfuse/references/setup.md 和 skills/langfuse/references/tool-reference.md。

工具（共 48 个）

类别	工具
跟踪	fetch_traces、fetch_trace
观察记录	fetch_observations、fetch_observation
路由	find_route_decisions、get_route_decision、summarize_route_decisions、find_low_confidence_route_decisions
会话	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_dataset_runs、get_dataset_run、list_dataset_run_items、create_dataset_run_item、delete_dataset_run
标注队列	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
指标	query_metrics、get_metrics_schema
架构	get_data_schema

在 Observations API v2 中，跟踪由根观察记录构成。fetch_traces 不会返回没有根观察记录的跟踪，而 fetch_trace 无法找到没有观察记录的跟踪。

读取数据集运行信息时，如果已安装的 Langfuse SDK 提供实验 API（Python SDK 4.13.1+），则会使用该 API。对于未提供实验 API 的自托管服务，仍会回退到旧路由。delete_dataset_run 在旧删除路由仍可用时会使用该路由；该路由移除后，只有传入 delete_traces=True 时才会删除运行的跟踪。删除跟踪也会删除观察记录和相关评分。create_dataset_run_item 仍使用旧关联 API；该 API 停用后，请通过 SDK 实验运行器或 OTel 摄取来创建实验数据。

数据集条目更新（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"})

指标查询

query_metrics 会在服务端聚合遥测数据（成本、延迟、令牌数、计数、评分值），让 Agent 无需提取原始跟踪记录，也能回答“推理花了多少钱？”或“各模型的 p95 延迟是多少？”之类的问题。调用 get_metrics_schema 可查看完整的视图、维度和度量目录。

query_metrics(
    view="observations",
    metrics=[{"measure": "totalCost", "aggregation": "sum"}, {"measure": "latency", "aggregation": "p95"}],
    dimensions=["providedModelName"],
    age=1440,  # last 24h; or pass from_timestamp / to_timestamp
)

高基数字段（id、traceId、userId、sessionId）必须用于 filters，而不能用于 dimensions。v2 指标端点仅适用于 Langfuse Cloud；可自托管的实例可能会返回 404。

按需加载工具

仅加载所需的工具组，以减少令牌开销：

langfuse-mcp --tools traces,prompts

可用的组：traces、observations、routing、sessions、exceptions、prompts、datasets、annotation_queues、scores、metrics、schema

routing 组与路由器无关。它会读取 Langfuse span 观测， metadata.schema_version: "mcp.route_decision.v1"，并筛选存储在观测元数据中的路由决策 字段，例如 decision_id、router_name、 provider 和 capability_id。

只读模式

禁用所有写入操作，以便安全地进行只读访问：

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_dataset_run_item、delete_dataset_run、create_annotation_queue、create_annotation_queue_item、update_annotation_queue_item、delete_annotation_queue_item、create_annotation_queue_assignment、delete_annotation_queue_assignment

默认输出模式

设置 MCP 暴露的默认 output_mode，这样省略该参数的客户端就会自动使用你偏好的模式：

langfuse-mcp --default-output-mode full_json_file
# Or via environment variable
LANGFUSE_MCP_DEFAULT_OUTPUT_MODE=full_json_file langfuse-mcp

支持的值：compact、full_json_string、full_json_file

这会更新 MCP 工具架构中显示的默认值。客户端仍可在调用时显式传入 output_mode，以覆盖默认值。

其他客户端

Cursor

在项目中创建 .cursor/mcp.json（或在全局路径 ~/.cursor/mcp.json 中创建）：

{
  "mcpServers": {
    "langfuse": {
      "command": "uvx",
      "args": ["langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-...",
        "LANGFUSE_SECRET_KEY": "sk-...",
        "LANGFUSE_HOST": "https://cloud.langfuse.com",
        "LANGFUSE_MCP_DEFAULT_OUTPUT_MODE": "full_json_file"
      }
    }
  }
}

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

使用配置文件管理多个项目（stdio）

对于本地客户端（Claude Code、Codex、Cursor），请将每个 Langfuse 项目的凭据保存在配置文件中，并为每个项目注册一个 MCP 服务。每个服务 都使用 --profile <name> 启动。

该文件采用 TOML 格式，位于 $XDG_CONFIG_HOME/langfuse-mcp/profiles.toml（如果 未设置 XDG_CONFIG_HOME，则位于 ~/.config/langfuse-mcp/profiles.toml）。使用 --profiles-file PATH 或 LANGFUSE_MCP_PROFILES_FILE 指定其他文件。

[profiles.prod]
host = "https://cloud.langfuse.com"
public_key = "pk-lf-..."
secret_key_env = "LANGFUSE_PROD_SECRET_KEY"   # read the secret from this env var

[profiles.staging]
host = "https://langfuse.staging.example.com"
public_key = "pk-lf-..."
secret_key = "sk-lf-..."                       # or give the value directly

public_key、secret_key 和 host 均可设置为字面值，也可使用 <field>_env 键指定存放该值的环境变量名称。 host 默认为 https://cloud.langfuse.com。

claude mcp add langfuse-prod -- uvx langfuse-mcp --profile prod
claude mcp add langfuse-staging -- uvx langfuse-mcp --profile staging

{
  "mcpServers": {
    "langfuse-prod": {
      "command": "uvx",
      "args": ["langfuse-mcp", "--profile", "prod"]
    },
    "langfuse-staging": {
      "command": "uvx",
      "args": ["langfuse-mcp", "--profile", "staging"]
    }
  }
}

优先级依次为：CLI 标志（--public-key、--secret-key、--host）> 环境 变量（LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY、LANGFUSE_HOST）> 所选配置文件 > 默认值。当环境变量覆盖配置文件中的值时，服务会记录警告。如果配置文件名称未知或配置文件 缺失，服务会报错并停止，同时指出文件路径和可用的 配置文件。未指定 --profile 时，可通过 LANGFUSE_MCP_PROFILE 选择配置文件。

HTTP 传输 — 多个项目共用一个服务

运行一个持久服务实例，并通过在 Authorization 标头中传递凭据，将每个 MCP 客户端路由到各自的 Langfuse 项目。

# Start a shared server (binds to localhost by default)
docker run -d -p 127.0.0.1:8000:8000 \
  -e LANGFUSE_HOST=https://cloud.langfuse.com \
  ghcr.io/avivsinai/langfuse-mcp:latest \
  --transport streamable-http --bind-host 0.0.0.0

安全提示： --bind-host 0.0.0.0 会在所有网络接口上公开端口。在生产环境中，请将服务置于终止 TLS 的反向代理（nginx、Caddy、Cloudflare Tunnel）之后，并强制使用 HTTPS。包含密钥的 Authorization 标头会以明文形式通过纯 HTTP 传输。如果设置了启动凭据，代理必须强制进行身份验证；否则，没有 Authorization 标头的未验证调用方可以使用默认项目。对于共享的公共 HTTP 部署，除非前置代理对每个请求进行身份验证，否则请省略默认的 LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY 凭据。

在 MCP 客户端中分别注册每个项目，并将其凭据作为 Basic 身份验证标头传递（base64(public_key:secret_key)）：

# Generate the header value for each project:
echo -n "pk-lf-YOURKEY:sk-lf-YOURSECRET" | base64
# cGstbGYtWU9VUktFWTpzay1sZi1ZT1VSU0VDUkVU

# Register in Claude Code (one entry per project):
claude mcp add langfuse-audit \
  --transport http http://localhost:8000/mcp \
  -H "Authorization: Basic cGstbGYtWU9VUktFWTpzay1sZi1ZT1VSU0VDUkVU"

claude mcp add langfuse-staging \
  --transport http http://localhost:8000/mcp \
  -H "Authorization: Basic <base64 for staging project>"

身份验证语义： 此处的 Basic 携带的是 Langfuse API 密钥，而非用户密码。若未提供标头，则回退到启动环境变量（LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY）。任何格式错误的标头都会被直接拒绝，不会静默回退到其他项目。

可选环境变量

变量	默认值	说明
LANGFUSE_MAX_AGE_DAYS	7	限制基于时间的工具（fetch_traces、fetch_observations 等）的回溯窗口。请将其设为与 Langfuse 实例的数据保留期限一致的值，例如，保留期限为 30 天时设为 30。
LANGFUSE_MCP_PROFILE	未设置	从配置文件加载的配置档案；等同于 --profile。请参阅使用配置档案管理多个项目。
LANGFUSE_MCP_PROFILES_FILE	$XDG_CONFIG_HOME/langfuse-mcp/profiles.toml	配置档案文件的路径；等同于 --profiles-file。
LANGFUSE_MCP_TRACE_TIMEOUT_SECONDS	120	获取单条 Trace（fetch_trace）时每个请求的读取超时时间（秒）。如果包含 include_observations=True 的大型 Trace 超时，请调高此值。必须为正整数。

开发

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

许可证

MIT