SuperAPI AI 工具集
合作ENAI 行业资讯收藏
全部工具AI编程工具langfuse-mcp

langfuse-mcp

langfuse-mcp 是一个面向 Langfuse 的本地 Model Context Protocol（MCP）服务器与配套技能，让 AI 智能体能够查询 Langfuse 的追踪（trace）、会话（session）与异常数据，用于调试和可观测性分析。它支持 Claude Code、Codex、Cursor 等任意 MCP 客户端，提供 48 个工具，覆盖追踪、观测、路由决策、会话、异常、提示词、数据集、标注队列、评分、指标与 schema 等分组，并支持按需加载工具组、只读模式、多项目 profile 与 HTTP 共享部署。

访问官网

工具介绍

用途

langfuse-mcp 是一个面向 Langfuse 的本地 Model Context Protocol（MCP）服务器，同时附带一个第一方 langfuse 技能（skill）。它让 AI 智能体能够查询 Langfuse 的追踪数据，从而增强调试与可观测性能力。官方说明指出：本地调试场景使用 langfuse-mcp，托管、零安装、覆盖更广 API（评分写入、评论、模型、媒体等）的场景使用官方 Langfuse MCP。截至 2026 年 6 月，定位为「langfuse-mcp 用于本地调试，原生 MCP 用于托管广度」。

主要能力

  • 调试追踪（traces）、会话（sessions）与异常（exceptions），可从 Claude Code、Codex、Cursor 或任意 MCP 客户端使用。
  • 提供路由决策工具（route-decision tools）、紧凑/文件转储输出（compact / file-dump output）。
  • 共提供 48 个工具，分组包括：traces、observations、routing、sessions、exceptions、prompts、datasets、annotation_queues、scores、metrics、schema。
  • 异常工具通过 observation level == "ERROR" 检测错误（严格判定，仅有非空 status_message 不算）。find_exceptions 返回 {group, count, observation_id, trace_id}（最多 50 组），每组带一个代表性 observation/trace ID；find_exceptions_in_file 还会产出完整错误记录。计数描述的是 error 级别的 observation，而非单个异常事件，因此 get_error_count 返回 exception_count: null。异常详情来自记录的元数据（exception.type / exception.message / exception.stacktrace，位于顶层或 metadata.attributes 下），缺失值为 null。结果不是时间点快照。
  • 指标查询：query_metrics 在服务端聚合遥测数据（成本、延迟、token、计数、评分值），可回答「推理花了多少钱」「按模型的 p95 延迟是多少」等问题，无需拉取原始追踪。调用 get_metrics_schema 可获取完整的 view/dimension/measure 目录。高基数（high-cardinality）字段（id、traceId、userId、sessionId）必须用于 filters，不能用作 dimensions。v2 指标端点仅限 Langfuse Cloud，自托管实例可能返回 404。
  • 数据集项更新采用 upsert：要编辑已有项，调用 create_dataset_item 并传入 item_id；ID 存在则更新，否则新建。
  • 数据集运行读取在已安装的 Langfuse SDK 暴露 experiments API 时使用该 API（Python SDK 4.13.1+）；旧路由作为自托管服务器的回退。delete_dataset_run 在旧删除路由可用时使用它；该路由移除后，仅当传入 delete_traces=True 时才删除该运行的追踪。删除追踪也会移除观测与相关评分。create_dataset_run_item 仍使用旧链接 API；该 API 消失后，需通过 SDK experiment runner 或 OTel 摄取创建实验数据。
  • 在 Observations API v2 上，追踪由根观测（root observations）构建。fetch_traces 会省略没有根观测的追踪，fetch_trace 无法找到没有任何观测的追踪。

使用方式

安装：uvx langfuse-mcp，并配置 Langfuse API 密钥。需要 uv（用于 uvx）与 Python 3.10 或更新版本；CI 验证 Python 3.10 至 3.14。凭据从 Langfuse Cloud → Settings → API Keys 获取；自托管则用实例 URL 作为 LANGFUSE_HOST。如需显式固定 CI 验证过的解释器，可在 langfuse-mcp 前加 --python 3.14。重启 CLI 后，用 /mcp（Claude Code）或 codex mcp list（Codex）验证。

选择性工具加载：只加载需要的工具组以减少 token 开销。可用分组：traces、observations、routing、sessions、exceptions、prompts、datasets、annotation_queues、scores、metrics、schema。routing 组与路由器无关，它读取带有 metadata.schema_version: "mcp.route_decision.v1" 的 Langfuse span 观测，并按观测元数据中的路由决策字段（如 decision_id、router_name、provider、capability_id）过滤。

只读模式：可禁用所有写操作以获得更安全的只读访问。被禁用的操作包括：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，使省略该参数的客户端自动使用偏好模式。支持的值：compact、full_json_string、full_json_file。这会更新 MCP 工具 schema 中显示的默认值，客户端仍可在单次调用中显式传入 output_mode 覆盖。

Cursor 配置：在项目中创建 .cursor/mcp.json（或全局 ~/.cursor/mcp.json）。也支持 Docker（单项目）与多项目 profile（stdio）。

多项目 profile：本地客户端（Claude Code、Codex、Cursor）可将每个 Langfuse 项目的凭据放在 profiles 文件中，并为每个项目注册一个 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 读取其他文件。public_key、secret_key、host 各取字面值，或取 <field>_env 键（命名存放该值的环境变量）。host 默认 https://cloud.langfuse.com。优先级：CLI 标志（--public-key、--secret-key、--host）> 环境变量（LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY、LANGFUSE_HOST）> 所选 profile > 默认值。环境变量覆盖 profile 值时服务器会记录警告。未知 profile 名或缺失 profiles 文件会以错误停止服务器，错误中会指明文件与可用 profile。未给出 --profile 时，LANGFUSE_MCP_PROFILE 选择 profile。

HTTP 传输（多项目共享服务器）：运行一个持久服务器实例，通过在 Authorization 头中传递凭据，将每个 MCP 客户端路由到各自的 Langfuse 项目。安全提示：--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)）传递。认证语义：此处的 Basic 承载的是 Langfuse API 密钥，而非用户密码。缺少该头时回退到启动环境凭据（LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY）。任何格式错误的头都会被直接拒绝——不会静默回退到其他项目。

配套技能：仓库附带第一方 langfuse 技能，供 Claude Code 与 Codex 使用，为智能体提供追踪调试、异常分诊、延迟分析、提示词管理与数据集工作的具体操作手册。推荐通过 skills 安装，也支持手动安装。安装后可让智能体知道何时该使用 Langfuse 以及优先调用哪些 MCP 工具。MCP 服务器提供工具，技能提供面向智能体的工作流。相关文件：skills/langfuse/SKILL.md、skills/langfuse/references/setup.md、skills/langfuse/references/tool-reference.md。

适用场景

  • 在 Claude Code、Codex、Cursor 等 MCP 客户端中本地调试 LLM 应用的追踪、会话与异常。
  • 快速定位失败追踪（官方称「2 分钟看到失败追踪」）。
  • 分析延迟、成本、token 等指标。
  • 管理提示词、数据集与标注队列。
  • 多项目凭据隔离与共享 HTTP 服务器部署。

限制

  • 需要 uv（用于 uvx）与 Python 3.10+。
  • 异常检测严格依赖 observation level == "ERROR"；计数为 error 级别观测数而非异常事件数；结果非时间点快照。
  • v2 指标端点仅限 Langfuse Cloud，自托管可能返回 404。
  • 在 Observations API v2 上，无根观测的追踪会被 fetch_traces 省略，无观测的追踪无法被 fetch_trace 找到。
  • 数据集运行相关 API 存在版本与回退限制，部分旧路由移除后行为会变化。
  • HTTP 共享部署存在明文传输与未认证访问风险，需反向代理与认证保护。
  • 官方未提供具体收费与价格信息。

同类工具

查看分类