langfuse

Langfuse MCP 服务

用于只读分析 Langfuse 大模型追踪记录和观察项的 MCP 服务。旨在帮助 Agent 深入检查追踪数据、调试大模型流水线，并分析成本和延迟。

亮点

• 按名称、用户、会话、标签、时间戳和环境浏览及筛选追踪记录
• 深入查看完整追踪详情，包括所有嵌套观察项和评分
• 按类型（GENERATION、SPAN、EVENT）、模型、级别等列出和筛选观察项
• 自动将大型载荷（>1000 个字符）截断并保存到 /tmp 文件，附带便于 grep 搜索的引用
• 只读——不执行写入操作，可安全使用，不会有修改数据的风险

功能

工具

工具	描述
get_traces	使用筛选条件和分页列出追踪记录。返回精简摘要（不含 I/O 字段）。
get_trace_detail	根据 ID 获取完整追踪记录，包括观察项、评分、输入/输出和元数据。
get_observations	根据 traceId、类型、级别等筛选并列出观察项。返回精简摘要。
get_observation	根据 ID 获取完整观察项，包括输入、输出、模型参数、用量和成本详情。

资源

资源	描述
langfuse://config	服务配置和状态（用于调试）

大型载荷处理

追踪记录和观察项数据通常包含非常大的输入/输出字段（完整提示词、补全内容等）。此服务会自动：

1. 将任何超过 1000 个字符的字符串字段截断
2. 将完整内容保存到 /tmp/langfuse_*.txt 文件
3. 在截断后的输出中包含文件路径

然后，Agent 可以使用 grep 在这些文件中搜索特定内容，而无需将整个载荷加载到上下文中。

配置

环境变量

变量	必需	描述	默认值
LANGFUSE_SECRET_KEY	是	Langfuse 密钥（sk-lf-...）	-
LANGFUSE_PUBLIC_KEY	是	Langfuse 公钥（pk-lf-...）	-
LANGFUSE_BASE_URL	否	Langfuse API 基础 URL	https://cloud.langfuse.com

Claude 桌面端配置

macOS：~/Library/Application Support/Claude/claude_desktop_config.json

Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["-y", "langfuse-observability-mcp-server"],
      "env": {
        "LANGFUSE_SECRET_KEY": "sk-lf-your-secret-key",
        "LANGFUSE_PUBLIC_KEY": "pk-lf-your-public-key",
        "LANGFUSE_BASE_URL": "https://us.cloud.langfuse.com"
      }
    }
  }
}

开发

# Install dependencies
npm run install-all

# Build
npm run build

# Development mode
npm run dev

# Run functional tests
npm test

# Run integration tests
npm run test:integration

# Run manual tests (requires .env with real credentials)
npm run test:manual

许可证

MIT