Langfuse MCP

Langfuse MCP Server

版本 1.4.2 —— 用于 Langfuse 分析的安全 MCP 服务，具备全面的安全功能，并提供只读/读写双模式，确保安全运行。

🔒 安全优先设计（v1.4.0 新增）

• 双运行模式 —— 默认采用安全的只读模式，写入操作需明确选择启用
• 三层安全防护 —— 环境、工具列表和运行时验证
• 写入工具前缀 —— 所有数据修改操作均使用清晰的 write_* 前缀
• 确认提示 —— 破坏性操作必须确认
• 全面的审计日志 —— 记录所有写入操作，以满足合规和安全要求

功能

• 32+ 个全面的工具 —— 涵盖完整的分析、数据集管理和评论协作功能
• 安全模式系统 —— 提供只读（默认）和读写模式，读写模式需明确选择启用
• 成本与使用情况分析 —— 按模型、服务、环境和时间段提供详细分类
• 数据集管理 —— 创建、整理和管理测试数据集，并提供验证示例
• 评论协作 —— 为跟踪记录、观测、会话和提示词添加评论
• 跟踪记录分析与调试 —— 提供高级筛选、搜索和详细的跟踪记录检查
• 系统管理 —— 健康监控、模型管理和提示词模板操作
• 实时测试 —— 包含模式验证的全面测试套件

v1.4.0 新功能

🔒 安全与模式系统：

• 默认采用只读模式 —— 仅允许读取操作
• 读写模式需明确选择启用，可修改数据
• 写入工具使用前缀（write_create_dataset、write_delete_dataset_item 等）
• 破坏性操作需确认
• 全面记录所有写入操作的审计日志

🛠️ 功能增强：

• 提供 32+ 个工具，涵盖分析、数据集管理和协作
• 单个 CLI 二进制文件，搭配直观的模式标志：langfuse-mcp
• 过渡期间支持旧版工具
• 根据模式筛选工具并显示相应描述

✅ 已可用于生产环境：

• 三层安全验证
• 全面的测试覆盖，包括模式验证
• 清晰的错误消息和使用指导
• 满足合规要求的结构化审计日志

安装

选项 1：使用 npx（推荐）

只读模式（安全默认设置）：

# Only analytics and read operations - safe for most users
npx @therealsachin/langfuse-mcp
# OR explicitly use readonly binary
langfuse-mcp-ro

读写模式（需明确选择启用）：

# ⚠️ Enables write operations - can modify your Langfuse data
LANGFUSE_MCP_MODE=readwrite npx @therealsachin/langfuse-mcp
# OR use CLI flag
langfuse-mcp --readwrite

选项 2：本地开发

git clone https://github.com/therealsachin/langfuse-mcp.git
cd langfuse-mcp
npm install
npm run build

# Test readonly mode
LANGFUSE_MCP_MODE=readonly node build/index.js

# Test readwrite mode
LANGFUSE_MCP_MODE=readwrite node build/index.js

配置

基本配置

为每个 Langfuse 项目设置环境变量：

LANGFUSE_PUBLIC_KEY=pk-lf-xxx
LANGFUSE_SECRET_KEY=sk-lf-xxx
LANGFUSE_BASEURL=https://us.cloud.langfuse.com

模式配置（v1.4.1 新增）

使用 CLI 标志或环境变量控制服务运行模式：

CLI 标志（推荐用于 npx）：

# Read-only mode (default, safe)
npx @therealsachin/langfuse-mcp

# Read-write mode (explicit opt-in)
npx @therealsachin/langfuse-mcp --readwrite

# Alternative explicit flag syntax
npx @therealsachin/langfuse-mcp --mode=readonly
npx @therealsachin/langfuse-mcp --mode=readwrite

环境变量（兼容旧版）：

# Readonly mode (default, safe)
LANGFUSE_MCP_MODE=readonly

# Readwrite mode (explicit opt-in)
LANGFUSE_MCP_MODE=readwrite

Claude Desktop 配置

只读模式（推荐大多数用户使用）：

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["@therealsachin/langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-your-key",
        "LANGFUSE_SECRET_KEY": "sk-lf-your-secret",
        "LANGFUSE_BASEURL": "https://us.cloud.langfuse.com"
      }
    }
  }
}

读写模式（仅限高级用户）：

{
  "mcpServers": {
    "langfuse": {
      "command": "npx",
      "args": ["@therealsachin/langfuse-mcp", "--readwrite"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-your-key",
        "LANGFUSE_SECRET_KEY": "sk-lf-your-secret",
        "LANGFUSE_BASEURL": "https://us.cloud.langfuse.com"
      }
    }
  }
}

🔒 安全最佳实践

⚠️ 重要：切勿将真实 API 凭据提交到版本控制中！

内置安全功能（v1.4.2 新增）

此 MCP 服务包含多层安全防护：

🛡️ 强制使用 HTTPS

• 自动验证确保所有连接均使用 HTTPS 协议
• 防止以明文传输凭据和敏感数据
• 运行时检查会拒绝任何 HTTP URL，并显示清晰的错误消息
• 保障生产环境安全，确保与 Langfuse API 进行安全通信

🔍 URL 脱敏

• 自动隐藏错误日志中的敏感查询参数
• 防止信息泄露，避免凭据在日志中泄漏
• 智能筛选：保留调试信息，同时移除机密信息
• 保护审计跟踪记录，确保日志整洁并符合合规要求

🚨 提交前安全钩子

• 自动检测凭据：防止意外提交真实 API 密钥
• Langfuse 专用模式：扫描 pk-lf- 和 sk-lf- 格式的密钥
• 通用密钥检测：捕获常见凭据模式
• 构建验证：确保代码在提交前可以编译
• Git 集成：使用 Husky 无缝集成工作流

如需在开发环境中启用提交前钩子：

npm install husky --save-dev
npx husky install
# Hooks are automatically configured - no manual setup needed!

安全凭据管理

1. 使用环境变量：将凭据存储在环境变量中，切勿在源文件中硬编码
2. 在本地使用 .env 文件：创建 .env 文件用于本地开发（该文件已列入 .gitignore）
3. 使用占位值：在已提交的文件中，使用 pk-lf-your-public-key 之类的占位值
4. 定期轮换密钥：定期在 Langfuse 控制面板中生成新的 API 密钥
5. 限制密钥权限：使用仅具备最低必要权限的项目专用密钥

请勿这样做：

# ❌ NEVER commit real credentials like this:
LANGFUSE_PUBLIC_KEY=pk-lf-REAL-KEY-NEVER-COMMIT-THIS
LANGFUSE_SECRET_KEY=sk-lf-REAL-SECRET-NEVER-COMMIT-THIS

请这样做：

# ✅ Use placeholder values in committed files:
LANGFUSE_PUBLIC_KEY=pk-lf-your-actual-public-key
LANGFUSE_SECRET_KEY=sk-lf-your-actual-secret-key

# ✅ Store real credentials in .env file (never committed):
# Create a .env file in your project root with your actual credentials

用于生产部署：

• 使用安全的环境变量管理方式（例如 Kubernetes Secrets、Docker secrets、云服务提供商的密钥管理器）
• 切勿将凭据包含在 Docker 镜像或 CI/CD 日志中
• 遵循最小权限访问原则

可用工具（共 18 个）

核心分析工具（6 个）

1. list_projects - 列出所有已配置的 Langfuse 项目
2. project_overview - 获取项目的成本、令牌用量和追踪摘要
3. usage_by_model - 按 AI 模型细分用量和成本
4. usage_by_service - 按服务／功能标签分析用量
5. top_expensive_traces - 查找成本最高的追踪
6. get_trace_detail - 获取特定追踪的详细信息

扩展分析工具（6 个）

7. get_projects - list_projects 的别名（列出可用的 Langfuse 项目）
8. get_metrics - 使用灵活的筛选条件查询聚合指标（成本、令牌用量、次数）
9. get_traces - 使用全面的筛选选项获取追踪
10. get_observations - 获取 LLM 生成内容／跨度及其详情和筛选结果
11. get_cost_analysis - 按模型／用户／每日趋势进行专项成本细分
12. get_daily_metrics - 获取每日用量趋势、模式和平均值

系统与管理工具（6 个）

13. get_observation_detail - 获取特定观测／生成内容的详细信息
14. get_health_status - 监控 Langfuse 系统的运行状况和状态
15. list_models - 列出项目中所有可用的 AI 模型
16. get_model_detail - 获取特定 AI 模型的详细信息
17. list_prompts - 使用筛选和分页列出所有提示词模板
18. get_prompt_detail - 获取特定提示词模板的详细信息

在 Claude Desktop 中使用

将以下内容添加到 claude_desktop_config.json：

选项 1：使用 npx（推荐）

{
  "mcpServers": {
    "langfuse-analytics": {
      "command": "npx",
      "args": ["@therealsachin/langfuse-mcp"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-xxx",
        "LANGFUSE_SECRET_KEY": "sk-lf-xxx",
        "LANGFUSE_BASEURL": "https://us.cloud.langfuse.com"
      }
    }
  }
}

选项 2：本地安装

{
  "mcpServers": {
    "langfuse-analytics": {
      "command": "node",
      "args": ["/path/to/langfuse-mcp/build/index.js"],
      "env": {
        "LANGFUSE_PUBLIC_KEY": "pk-lf-xxx",
        "LANGFUSE_SECRET_KEY": "sk-lf-xxx",
        "LANGFUSE_BASEURL": "https://us.cloud.langfuse.com"
      }
    }
  }
}

示例查询

与 Claude Desktop 集成后，你可以提出以下问题：

分析查询

• “显示过去 7 天的成本概览”
• “本月哪些 AI 模型的成本最高？”
• “找出昨天成本最高的 10 条追踪”
• “按服务细分生产环境中的用量”
• “显示追踪 xyz-123 的详细信息”

系统管理查询

• “检查我的 Langfuse 系统的运行状况”
• “列出我项目中所有可用的 AI 模型”
• “显示 GPT-4 模型的详细信息”
• “我有哪些可用的提示词模板？”
• “获取 ‘customer-support’ 提示词的详细信息”

高级分析

• “显示观测 abc-123 的详细信息”
• “过去一个月的每日成本趋势如何？”
• “找出所有成本超过 $0.10 的追踪”
• “哪些用户产生的成本最高？”

开发

# Watch mode for development
npm run watch

# Test with MCP Inspector
npm run inspector

# Test endpoints (requires .env file)
npm run test

使用真实 Langfuse 数据进行测试

如需针对真实 Langfuse 数据进行全面测试，请在项目根目录中创建 .env 文件：

# .env file (never commit this - it's in .gitignore)
LANGFUSE_PUBLIC_KEY=pk-lf-your-actual-public-key
LANGFUSE_SECRET_KEY=sk-lf-your-actual-secret-key
LANGFUSE_BASEURL=https://us.cloud.langfuse.com

测试套件（npm run test）会使用 dotenv 自动加载这些凭据，并针对你的 Langfuse 项目运行 13 项全面测试：

• ✅ 使用真实成本／令牌数据查看项目概览
• ✅ 使用服务器端排序获取跟踪记录
• ✅ 分析成本最高的跟踪记录
• ✅ 汇总每日指标
• ✅ 成本分析明细
• ✅ 健康状态监控
• ✅ 模型和提示词管理
• ✅ 获取观察详情

注意：.env 文件会自动加入 git 忽略列表，以保护你的凭据安全。

发布到 NPM

✅ 软件包已发布！ 可通过以下方式获取：

# Install and run directly with npx
npx @therealsachin/langfuse-mcp

# Or install globally
npm install -g @therealsachin/langfuse-mcp

软件包信息：

• 名称： @therealsachin/langfuse-mcp
• 版本： 1.1.1
• NPM 地址： https://www.npmjs.com/package/@therealsachin/langfuse-mcp

项目结构

src/
├── index.ts              # Main server entry point
├── config.ts             # Project configuration loader
├── langfuse-client.ts    # Langfuse client wrapper with 18+ API methods
├── types.ts              # TypeScript type definitions
└── tools/                # All 18 MCP tools
    # Core Analytics Tools (6)
    ├── list-projects.ts
    ├── project-overview.ts
    ├── usage-by-model.ts
    ├── usage-by-service.ts
    ├── top-expensive-traces.ts
    ├── get-trace-detail.ts
    # Extended Analytics Tools (6)
    ├── get-projects.ts          # Alias for list-projects
    ├── get-metrics.ts           # Aggregated metrics
    ├── get-traces.ts            # Trace filtering
    ├── get-observations.ts      # LLM generations
    ├── get-cost-analysis.ts     # Cost breakdowns
    ├── get-daily-metrics.ts     # Daily trends
    # System & Management Tools (6)
    ├── get-observation-detail.ts    # Observation details
    ├── get-health-status.ts         # Health monitoring
    ├── list-models.ts               # AI models listing
    ├── get-model-detail.ts          # Model details
    ├── list-prompts.ts              # Prompt templates
    └── get-prompt-detail.ts         # Prompt details

docs/                     # Comprehensive documentation
├── ARCHITECTURE.md       # System design and patterns
├── DEVELOPER_GUIDE.md    # Development workflows
├── TECHNICAL_DIAGRAMS.md # Visual system flows
├── IMPLEMENTATION_NOTES.md # API implementation details
└── DOCUMENTATION_INDEX.md # Navigation guide

test-endpoints.js         # Comprehensive test suite (13 tests)

API 集成

此服务集成了多个 Langfuse 公共 API 端点：

核心分析 API

• /api/public/metrics - 使用带有 JSON 查询参数的 GET 方法获取汇总分析数据
• /api/public/metrics/daily - 每日使用指标和成本明细
• /api/public/traces - 跟踪记录列表、筛选及单条跟踪记录获取
• /api/public/observations - 详细的观察分析和 LLM 生成指标

系统管理 API

• /api/public/observations/{id} - 单条观察记录详情和元数据
• /api/public/health - 系统健康状态和监控
• /api/public/models - AI 模型列表和配置
• /api/public/prompts - 提示词模板管理和版本控制

API 实现说明：

• 指标 API：使用 GET 方法，并在 query 参数中传入 URL 编码的 JSON
• 跟踪记录 API：支持高级筛选、分页和排序
• 观察 API：提供详细的 LLM 生成数据和 span 数据
• 每日指标 API：用于每日汇总使用统计数据的专用端点
• 健康 API：用于系统状态监控的简单端点
• 模型／提示词 API：支持分页、筛选和详细信息获取

所有身份验证均由服务端使用你的 Langfuse API 密钥通过 Basic Auth 处理。

文档

有关详细架构、开发指南和技术图表，请参阅完整文档：

• docs/ARCHITECTURE.md - 系统设计、模式和实现细节
• docs/DEVELOPER_GUIDE.md - 开发工作流和常见任务
• docs/TECHNICAL_DIAGRAMS.md - 系统流程和组件图示
• docs/DOCUMENTATION_INDEX.md - 完整导航指南

故障排除

✅ 已修复：405 Method Not Allowed 错误

之前的问题：早期版本由于 API 使用方式不正确，会遇到“405 Method Not Allowed”错误。

解决方案：当前版本已通过采用正确的 Langfuse API 实现修复此问题：

• 指标 API：现使用 GET 方法，并在 URL 编码的 JSON query 参数中传入数据（正确方式）
• 跟踪记录 API：使用实际的 /api/public/traces 端点并进行正确筛选
• 观察 API：使用 /api/public/observations 端点和正确参数
• 每日指标：使用专用的 /api/public/metrics/daily 端点

✅ 已修复：成本值返回为零

之前的问题：即使存在实际成本数据，成本分析工具仍返回零值。

解决方案：已通过修正 API 响应解析中的字段名称映射修复此问题：

• Metrics API 响应结构：API 返回的字段名称为聚合后的形式，例如 totalCost_sum、count_count、totalTokens_sum
• 更新字段访问方式：所有工具现在都使用正确的聚合字段名称，而不是直接使用字段名称
• 集成每日指标：成本分析现在使用 getDailyMetrics API，以便更清晰地按日拆分成本
• 受影响的工具：get-cost-analysis、get-metrics、usage-by-model、usage-by-service、project-overview、get-daily-metrics

✅ 已修复：响应大小和 API 参数问题

之前的问题：

1. get_observations 返回的响应超过 MCP 令牌限制（超过 200k 个令牌）
2. get_traces 返回 400 Bad Request 错误

已实施的解决方案：

• 控制 get_observations 响应大小：
  • 添加 includeInputOutput: false 参数（默认值），用于排除较大的提示词／响应内容
  • 添加 truncateContent: 500 参数，在包含内容时限制其大小
  • 将默认限制从 25 条观察结果降至 10 条
  • 启用后会截断输入／输出字段中的内容
• 修复 get_traces API 参数：
  • 添加对 orderBy 字段的参数验证
  • 增强错误日志记录，加入完整请求详情以便调试
  • 添加完善的错误处理，并返回详细错误信息

✅ 已修复：成本分析数据聚合

之前的问题：每日数据正常，但成本分析中总成本和模型明细均显示为零。

根本原因：尽管此前进行过修复，Metrics API 字段映射仍然有误。

解决方案：改用正常工作的 Daily Metrics API 数据进行所有聚合：

• 总成本计算：现在根据每日数据求和，而不再使用有问题的 Metrics API
• 模型明细：从每日使用数据中提取并汇总模型成本
• 每日明细：优化为复用已获取的每日数据
• 用户明细：仍使用 Metrics API，但增强了调试功能

结果：

• ✅ totalCost 现在会显示正确值（每日成本之和）
• ✅ byModel 现在会填充真实的模型成本明细
• ✅ byDay 仍然运行正常
• 🔍 byUser 包含调试功能，可用于排查剩余的字段映射问题

✅ 已修复：usage_by_model 的成本／令牌显示为零

之前的问题：usage_by_model 中观察结果计数正确，但成本和令牌均显示为零。

根本原因：成本计算受到了相同的 Metrics API 字段映射问题影响。

解决方案：采用与成本分析相同的每日指标方案：

• 主要方式：使用 getDailyMetrics API，从每日使用明细中汇总模型成本和令牌数
• 备用方式：如果 Daily API 调用失败，则使用增强了调试功能的原 Metrics API
• 数据聚合：正确地从每日数据中提取 totalCost、totalUsage 和 countObservations

结果：

• ✅ 模型现在会显示真实的 totalCost 值，而不是 0
• ✅ 模型现在会显示真实的 totalTokens 值，而不是 0
• ✅ observationCount 仍然运行正常

性能注意事项

API 效率：服务现在会高效地使用 Langfuse 原生端点：

• Langfuse 会在服务端处理指标查询，以实现最佳性能
• 在 API 层面进行轨迹和观察结果筛选，以减少数据传输
• 每日指标使用专用端点获取预聚合数据

环境变量

请确保正确设置以下环境变量：

LANGFUSE_PUBLIC_KEY=pk-lf-xxx     # Your Langfuse public key
LANGFUSE_SECRET_KEY=sk-lf-xxx     # Your Langfuse secret key
LANGFUSE_BASEURL=https://us.cloud.langfuse.com  # Your Langfuse instance URL