内容
# langfuse-mcp
[](https://www.npmjs.com/package/langfuse-mcp)
[](https://www.npmjs.com/package/langfuse-mcp)
[](https://github.com/hugoles/langfuse-mcp/actions/workflows/ci.yml)
[](https://nodejs.org)
[](LICENSE)
一个 [MCP](https://modelcontextprotocol.io) 服务器，暴露 [Langfuse](https://langfuse.com) REST API 作为工具，以便 Claude（或任何 MCP 客户端）可以在对话期间查询您的跟踪、观察、会话、分数、提示、数据集和指标。
在不离开您的助手的情况下，您可以提出以下问题：
- _“为什么跟踪 `abc123` 失败？请逐步解释其观察结果。”_
- _“列出用户 `alice@x.com` 的 5 个最近的 `level=ERROR` 跟踪记录。”_
- _“汇总按模型划分的今日生成成本。”_
- _“显示给我提示 `customer-support-v2` 的生产版本。”_
## 要求
- **Node.js 20 或更高版本** (`node --version`)。
- 一个具有 API 密钥的 Langfuse 项目（[cloud.langfuse.com → 设置 → API 密钥](https://cloud.langfuse.com/project/settings) 在 EU 云上，[us.cloud.langfuse.com](https://us.cloud.langfuse.com) 在 US 云上，或您的自托管实例）。
## 工具
所有工具都是只读的，并且使用您的项目密钥通过 HTTPS 调用 [Langfuse 公共 API](https://api.reference.langfuse.com) 进行基本身份验证。
### 跟踪和观察
| 工具 | 描述 |
| ------------------ | --------------------------------------------------------------- |
| `listTraces` | 列出跟踪记录并过滤。返回摘要元数据。 |
| `getTrace` | 获取单个跟踪记录 ID，包括完整的观察树。 |
| `listObservations` | 列出跨度、生成和事件并过滤。 |
| `getObservation` | 获取单个观察 ID。 |
### 会话
| 工具 | 描述 |
| -------------- | -------------------------------------------- |
| `listSessions` | 在时间范围内列出会话。 |
| `getSession` | 获取会话 ID，包括其跟踪记录。 |
### 分数
| 工具 | 描述 |
| ------------------ | ------------------------------------------------------------ |
| `listScores` | 列出分数并过滤。 |
| `getScore` | 获取单个分数 ID。 |
| `listScoreConfigs` | 列出分数配置（定义、范围、类别）。 |
| `getScoreConfig` | 获取分数配置 ID。 |
### 提示
| 工具 | 描述 |
| ------------- | ------------------------------------------------------------------------- |
| `listPrompts` | 列出提示定义，可选过滤名称、标签或标签。 |
| `getPrompt` | 获取提示 ID，可选固定为特定版本或标签。 |
### 数据集
| 工具 | 描述 |
| ------------------ | ------------------------------------------------------------- |
| `listDatasets` | 列出 Langfuse 中配置的数据集。 |
| `getDataset` | 获取数据集名称。 |
| `listDatasetItems` | 列出数据集中的项目（输入、预期输出、元数据）。 |
| `getDatasetItem` | 获取单个数据集项目 ID。 |
| `listDatasetRuns` | 列出数据集的评估运行。 |
| `getDatasetRun` | 获取特定数据集运行名称。 |
### 指标、模型等
| 工具 | 描述 |
| ----------------- | ------------------------------------------------------------------------------------------ |
| `getMetrics` | 运行自定义指标查询（计数、延迟、成本、token 使用）。传递 JSON 查询字符串。 |
| `getDailyMetrics` | 每日聚合使用量 / 成本 / 计数指标。 |
| `listModels` | 列出 Langfuse 已知的模型（用于成本 / token 归属）。 |
| `getModel` | 获取模型定义 ID。 |
| `listProjects` | 列出当前 API 密钥可访问的项目。 |
| `listComments` | 列出附加到跟踪记录、观察、会话或提示的评论。 |
| `getComment` | 获取评论 ID。 |
| `getMedia` | 获取媒体附件的元数据（图像、音频、文件）。 |
| `getHealth` | ping Langfuse 公共健康端点 — 用于凭证验证。 |
## 安装
使用 `npx` 零安装：
```bash
npx -y langfuse-mcp
```
或全局安装：
```bash
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`（EU）或 `https://us.cloud.langfuse.com`（US）或您的自托管 URL。 |
| `LANGFUSE_ENV_FILE` | 否 | 加载 `.env` 文件的可选路径，而不是 `./.env`。 |
> **在哪里获取我的密钥？** 在 Langfuse UI 中：**设置 → API 密钥 → 创建新的 API 密钥**。密钥范围限定在一个项目和一个区域（EU 与 US 是单独的帐户 — 将您的 `LANGFUSE_BASE_URL` 与您创建密钥的区域匹配）。
如果在工作目录中存在 `.env` 文件，则会自动加载它。参见 [`.env.example`](.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`
```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`):
```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`.
```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`):
```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` 中:
```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 设置中，添加：
```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"
}
}
}
}
```
## 与任何其他 MCP 客户端一起使用
服务器通过 stdio 讲话。任何 MCP 客户端都可以将其作为子进程启动：
```bash
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` 及其所有观察结果。”_
- _“用户 `alice@example.com` 本周收到了什么分数？”_
- _“获取提示 `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` 文件中的密钥引用：此服务器剥离周围的引号，但多余的空格仍可能破坏基本身份验证。重新粘贴密钥。
- 首先使用 `getHealth` 确认凭证，然后再运行其他工具。
**`npx` 始终使用旧版本**
```bash
npx -y langfuse-mcp@latest
```
`npx` 会积极地缓存软件包。`@latest` 后缀强制刷新。
**`LANGFUSE_BASE_URL 必须是完整的 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` 行。
- 确保 Node 20+ 位于您的 PATH 上（Claude Desktop 使用您的登录 shell PATH）。
- 完全退出 Claude Desktop（不仅仅是关闭窗口），然后重新启动。
**神秘的 `ERR_REQUIRE_ESM` / `Unexpected token` 启动时**
您的 Node 版本太旧。此软件包需要 Node ≥ 20。运行 `node --version` 并根据需要升级（例如，通过 [nvm](https://github.com/nvm-sh/nvm)）。
## 开发
```bash
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](CONTRIBUTING.md)。欢迎提交错误报告和 PR - 请在打开之前在本地运行 `npm run typecheck && npm run lint && npm test`。
## 安全
发现漏洞？请根据 [SECURITY.md](SECURITY.md) 中的描述私下报告。不要公开问题。
## 许可证
[MIT](LICENSE) © Hugoles。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器