Langfuse Mcp

langfuse-mcp

一个 MCP 服务，将 Langfuse REST API 封装为工具，让 Claude（或任何 MCP 客户端）在对话过程中查询你的追踪记录、观测记录、会话、评分、提示词、数据集和指标。

适用于这类问题：

• “追踪记录 abc123 为什么失败？请带我逐一了解它的观测记录。”
• “列出用户 [email protected] 最近的 5 条 level=ERROR 追踪记录。”
• “按模型汇总今天的生成成本。”
• “给我看看提示词 customer-support-v2 的生产版本。”

……无需离开你的助手。

要求

• Node.js 20 或更高版本（node --version）。
• 一个拥有 API 密钥的 Langfuse 项目（EU 云端可前往 cloud.langfuse.com → Settings → API Keys，US 云端可访问 us.cloud.langfuse.com，也可以使用你的自托管实例）。

工具

所有工具均为只读，通过 HTTPS 调用 Langfuse Public API，并使用你的项目密钥进行 Basic Auth 身份验证。

追踪记录与观测记录

工具	描述
listTraces	根据筛选条件列出追踪记录，并返回摘要元数据。
getTrace	按 ID 获取单条追踪记录，包括完整的观测记录树。
listObservations	根据筛选条件列出 spans、生成记录和事件。
getObservation	按 ID 获取单条观测记录。

会话

工具	描述
listSessions	列出指定时间范围内的会话。
getSession	按 ID 获取会话及其追踪记录。

评分

工具	描述
listScores	根据筛选条件列出评分。
getScore	按 ID 获取单条评分。
listScoreConfigs	列出评分配置（定义、范围、类别）。
getScoreConfig	按 ID 获取评分配置。

提示词

工具	描述
listPrompts	列出提示词定义，可按名称、标签或标记筛选。
getPrompt	按名称获取提示词，可固定到特定版本或标记。

数据集

工具	描述
listDatasets	列出 Langfuse 中配置的数据集。
getDataset	按名称获取数据集。
listDatasetItems	列出数据集中的条目（输入、预期输出、元数据）。
getDatasetItem	按 ID 获取单个数据集条目。
listDatasetRuns	列出数据集的评估运行。
getDatasetRun	按名称获取特定的数据集运行。

指标、模型与其他

工具	描述
getMetrics	运行自定义指标查询（计数、延迟、成本、令牌用量）。传入 JSON 查询字符串。
getDailyMetrics	每日汇总的用量 / 成本 / 计数指标。
listModels	列出 Langfuse 已知的模型（用于成本 / 令牌归因）。
getModel	按 ID 获取模型定义。
listProjects	列出当前 API 密钥可访问的项目。
listComments	列出附加到跟踪记录、观测结果、会话或提示词的评论。
getComment	按 ID 获取单条评论。
getMedia	获取媒体附件（图像、音频、文件）的元数据。
getHealth	Ping Langfuse 公共健康检查端点——可用于验证凭据。

安装

使用 npx，无需安装：

npx -y langfuse-mcp

或者全局安装：

npm i -g langfuse-mcp
langfuse-mcp --version

配置

服务会读取三个环境变量：

变量	必需	描述
LANGFUSE_PUBLIC_KEY	是	项目公钥（pk-lf-…）。
LANGFUSE_SECRET_KEY	是	项目密钥（sk-lf-…）。
LANGFUSE_BASE_URL	是	例如 https://cloud.langfuse.com（欧盟）或 https://us.cloud.langfuse.com（美国），也可以使用你的可自托管 URL。
LANGFUSE_ENV_FILE	否	可选的 .env 文件路径，用于替代 ./.env。

在哪里获取密钥？ 在 Langfuse UI 中：Settings → API Keys → Create new API keys。密钥仅适用于单个项目和单个区域（欧盟和美国是独立账户——请确保 LANGFUSE_BASE_URL 与创建密钥的区域匹配）。

如果工作目录中存在 .env 文件，系统会自动加载。入门文件请参阅 .env.example。

与 Claude Desktop 配合使用

编辑 claude_desktop_config.json：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-…",
        "LANGFUSE_SECRET_KEY": "sk-lf-…",
        "LANGFUSE_BASE_URL": "https://cloud.langfuse.com"
      }
    }
  }
}

编辑后重启 Claude Desktop。MCP 服务图标应显示在聊天输入框中。

与 Claude Code 配合使用

项目级配置（./.mcp.json）：

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-…",
        "LANGFUSE_SECRET_KEY": "sk-lf-…",
        "LANGFUSE_BASE_URL": "https://cloud.langfuse.com"
      }
    }
  }
}

用户级配置位于 ~/.claude.json，使用相同的结构。

与 Cursor 搭配使用

项目级：.cursor/mcp.json。用户级：~/.cursor/mcp.json。

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-…",
        "LANGFUSE_SECRET_KEY": "sk-lf-…",
        "LANGFUSE_BASE_URL": "https://cloud.langfuse.com"
      }
    }
  }
}

与 Cline (VS Code) 搭配使用

在 VS Code 设置（settings.json）中：

{
  "cline.mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-…",
        "LANGFUSE_SECRET_KEY": "sk-lf-…",
        "LANGFUSE_BASE_URL": "https://cloud.langfuse.com"
      }
    }
  }
}

与 Continue 搭配使用

在 ~/.continue/config.json 中：

{
  "mcpServers": [
    {
      "name": "langfuse",
      "command": "npx",
      "args": ["-y", "langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-…",
        "LANGFUSE_SECRET_KEY": "sk-lf-…",
        "LANGFUSE_BASE_URL": "https://cloud.langfuse.com"
      }
    }
  ]
}

与 Windsurf 搭配使用

在 Windsurf 的 MCP 设置中添加：

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-…",
        "LANGFUSE_SECRET_KEY": "sk-lf-…",
        "LANGFUSE_BASE_URL": "https://cloud.langfuse.com"
      }
    }
  }
}

与其他 MCP 客户端搭配使用

该服务通过 stdio 使用 MCP。任何 MCP 客户端都可以将其作为子进程启动：

LANGFUSE_PUBLIC_KEY=pk-lf-… \
LANGFUSE_SECRET_KEY=sk-lf-… \
LANGFUSE_BASE_URL=https://cloud.langfuse.com \
npx -y langfuse-mcp

试用

配置完成后，可以向助手提出以下问题：

• “使用 getHealth 工具确认 langfuse-mcp 已连接。”
• “列出最近 5 条 level=ERROR 的追踪记录。”
• “显示追踪记录 abc123 及其所有观测结果。”
• “用户 [email protected] 本周获得了哪些评分？”
• “获取提示词 customer-support 的生产版本。”
• “列出 eval-2026-q1 的数据集运行记录，并告诉我哪个记录的准确率评分最高。”

故障排除

首次调用时出现 401 Unauthorized

• 区域错误：Langfuse Cloud EU 和 US 是独立账户。请确保 LANGFUSE_BASE_URL 与创建密钥的区域相匹配（EU 使用 https://cloud.langfuse.com，US 使用 https://us.cloud.langfuse.com）。
• .env 中的密钥带引号：此服务会移除密钥两侧的引号，但多余的空格仍可能导致 Basic Auth 失败。请重新粘贴密钥。
• 先使用 getHealth 确认凭据，再运行其他工具。

npx 一直使用旧版本

npx -y langfuse-mcp@latest

npx 会积极缓存软件包。添加 @latest 后缀可强制刷新。

出现 LANGFUSE_BASE_URL must be a full URL 错误

最常见的原因是缺少协议。请使用 https://cloud.langfuse.com，而不是 cloud.langfuse.com。

自托管 Langfuse

使用部署的完整基础 URL，不带末尾斜杠或路径。例如：https://langfuse.mycompany.internal。服务会规范化单个末尾斜杠，但其他内容（/api、/public）会导致路径拼接失败。

MCP 服务图标未显示在 Claude Desktop 中

• 检查 Claude Desktop 日志：~/Library/Logs/Claude/mcp*.log（macOS）或 %APPDATA%\Claude\Logs\（Windows）。连接成功时，服务会向 stderr 写入一行 langfuse-mcp v… connected。
• 确保 PATH 中有 Node 20+（Claude Desktop 使用登录 shell 的 PATH）。
• 完全退出 Claude Desktop（不只是关闭窗口），然后重新启动。

启动时出现难以理解的 ERR_REQUIRE_ESM / Unexpected token

Node 版本过旧。此软件包要求 Node ≥ 20。运行 node --version，并在需要时升级（例如使用 nvm）。

开发

git clone https://github.com/hugoles/langfuse-mcp.git
cd langfuse-mcp
npm install
cp .env.example .env       # macOS/Linux
copy .env.example .env     # Windows cmd
npm run dev                # tsx src/index.ts (no build step)

其他脚本：

脚本	用途
npm run build	将 TypeScript 编译到 dist/。
npm start	运行构建后的服务。
npm run typecheck	tsc --noEmit。
npm run lint	ESLint。
npm run format / npm run format:check	Prettier 写入 / 检查。
npm test	Vitest。

贡献

请参阅 CONTRIBUTING.md。欢迎提交 Bug 报告和 PR——提交前请在本地运行 npm run typecheck && npm run lint && npm test。

安全

发现漏洞？请按照 SECURITY.md 中的说明私下报告。请勿公开提交 issue。

许可证

MIT © Hugoles。