Langfuse MCP服务器

版本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桌面配置

只读模式（建议大多数用户使用）：

{
  "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密钥的意外提交
廊坊特定图案 扫描以查找 pk-lf- 和 sk-lf- 格式键
一般秘密检测 捕获常见的凭据模式
构建验证 确保代码在提交前编译
Git集成 使用Husky实现无缝工作流集成

要在开发环境中启用预提交挂钩，请执行以下操作：

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

安全凭据管理

使用环境变量：将凭据存储在环境变量中，切勿将其硬编码在源文件中
在本地使用.env文件：创建一个 .env 本地开发文件（已在 .gitignore)
使用占位符值：在提交的文件中，使用占位符，如 pk-lf-your-public-key
定期旋转按键：定期在Langfuse仪表板中生成新的API密钥
限制密钥权限：使用具有最低所需权限的项目特定密钥

不该做什么：

# ❌ 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）

list_项目 -列出所有已配置的Langfuse项目
项目概述 -获取项目的成本、令牌和跟踪摘要
使用_型号 -按AI模型细分使用情况和成本
使用_服务 -按服务/功能标签分析使用情况
top_价格_比赛 -找到最昂贵的痕迹
get_trace_detail -获取特定跟踪的详细信息

扩展分析工具（6）

get_项目 -list_projects的别名（列出可用的Langfuse项目）
get_metrics -通过灵活的过滤查询聚合指标（成本、令牌、计数）
get_traces -使用全面的过滤选项获取痕迹
get_observations -通过详细信息和过滤获取LLM世代/跨度
get_cost_analysis -按型号/用户/日常趋势分列的专门成本明细
get_daily_metrics -每日使用趋势和模式与平均值

系统和管理工具（6）

get_observation_detail -获取特定观测/生成的详细信息
获取健康状态 -监控Langfuse系统的健康状况和状态
list_models -列出项目中可用的所有AI模型
get_model_detail -获取特定AI模型的详细信息
list_prompts -列出所有带有过滤和分页功能的提示模板
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模型最贵？”
“找出昨天十大最昂贵的痕迹”
“按生产环境的服务细分使用情况”
“显示跟踪xyz-123的详细信息”

系统管理查询

“检查我的Langfuse系统的健康状况”
“列出我项目中所有可用的AI模型”
“显示GPT-4型号的详细信息”
“我有哪些可用的提示模板？”
“获取“客户支持”提示的详细信息”

高级分析

“显示观察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个综合测试：

✅ 包含实际成本/代币数据的项目概述
✅ 使用服务器端排序进行跟踪检索
✅ 最昂贵的痕迹分析
✅ 每日指标汇总
✅ 成本分析明细
✅ 健康状态监测
✅ 模型和即时管理
✅ 观察细节检索

备注：The .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/@therelsachin/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 -使用GET和JSON查询参数进行聚合分析
/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：在URL编码的JSON中使用GET方法 query 参数
追踪API：支持高级过滤、分页和排序
API观察结果：提供详细的LLM生成和跨度数据
每日指标API：用于每日汇总使用统计的专用端点
健康API：用于系统状态监控的简单端点
模型/提示API：支持分页、过滤和详细检索

所有身份验证都在服务器端使用Langfuse API密钥进行基本身份验证。

文档

有关详细的体系结构、开发指南和技术图，请参阅全面的文件:

docs/ARCHITECTURE.md -系统设计、模式和实现细节
docs/DEVELOPER_GUIDE.md -开发工作流程和常见任务
文档/技术_数据库.md -可视化系统流程和组件图
docs/DOCUMETION_INDEX.md -完整的导航指南

故障排除

✅ 已修复：405方法不允许的错误

上期：由于API使用不正确，早期版本遇到“405方法不允许”错误。

解决方案：这是 固定的 在当前版本中使用正确的Langfuse API实现：

指标API：现在使用带有URL编码JSON的GET方法 query 参数（正确方法）
追踪API：使用实际 /api/public/traces 具有适当过滤的端点
API观察结果：用途 /api/public/observations 具有正确参数的端点
每日指标：使用专业 /api/public/metrics/daily 端点

✅ 固定：成本值返回为零

上期：即使存在实际成本数据，成本分析工具也返回零值。

解决方案：这是 固定的 通过纠正API响应解析中的字段名称映射：

度量API响应结构：API返回聚合字段名称，如 totalCost_sum, count_count, totalTokens_sum
更新了现场访问：所有工具现在都使用正确的聚合字段名，而不是直接字段名
每日指标集成：成本分析现在使用 getDailyMetrics API用于清洁日常成本细分
受影响的工具：获取成本分析、获取指标、按模型使用、按服务使用、项目概述、获取每日指标

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

以前的问题:

get_observations 返回的响应超过MCP令牌限制（200k+令牌）
get_traces 返回400个错误请求错误

应用的解决方案:

get_observations响应大小控制:

- 添加 includeInputOutput: false 参数（默认），用于排除大型提示/响应内容 - 添加 truncateContent: 500 包含时限制内容大小的参数 - 将默认限制从25个观察值降低到10个观察值 - 启用时对输入/输出字段进行内容截断

get_traces API参数修复:

- 添加了参数验证 orderBy 领域 - 增强的错误日志记录功能，提供完整的调试请求详细信息 - 添加了正确的错误处理和详细的错误响应

✅ 固定：成本分析数据聚合

上期：成本分析显示，总成本和模型细分为零，而每日数据正常工作。

根本原因：尽管早期进行了修复，但度量API字段映射仍然不正确。

解决方案：已切换为使用所有聚合的每日度量API数据：

总成本计算：现在根据每日数据求和，而不是破坏指标API
模型分解：从日常使用数据中提取和汇总模型成本
每日明细：优化以重用已获取的每日数据
用户细分：仍然使用度量API，但具有增强的调试功能

结果:

✅ totalCost 现在显示正确的值（每日成本之和）
✅ byModel 现在充满了真实的模型成本明细
✅ byDay 继续完美工作
🔍 byUser 包括调试以识别任何剩余的字段映射问题

✅ 修复：usage_by_model显示零成本/代币

上期：usage_by_model正确显示了观察计数，但所有成本和令牌均为零。

根本原因：影响成本计算的相同指标API字段映射问题。

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

主要方法：用途 getDailyMetrics API根据每日使用明细汇总模型成本和代币
后退方法：如果每日API失败，则返回到原始指标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

Langfuse MCP (langfuse-mcp-server)

快速接入

详细介绍

Langfuse MCP服务器

🔒 安全第一设计（v1.4.0中的新功能）

特性

v1.4.0的新增功能

安装

选项1：使用npx（推荐）

方案2：地方发展

配置

基本配置

模式配置（v1.4.1中的新功能）

Claude桌面配置

🔒 安全最佳实践

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

🛡️ HTTPS强制

🔍 URL净化

🚨 预提交安全挂钩

安全凭据管理

不该做什么：

该怎么办：

对于生产部署：

可用工具（共18个）

核心分析工具（6）

扩展分析工具（6）

系统和管理工具（6）

使用Claude Desktop

选项1：使用npx（推荐）

选项2：本地安装

查询示例

分析查询

系统管理查询

高级分析

发展

使用真实Langfuse数据进行测试

向NPM发布

项目结构

API集成

核心分析API

系统管理API

文档

故障排除

✅ 已修复：405方法不允许的错误

✅ 固定：成本值返回为零

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

✅ 固定：成本分析数据聚合

✅ 修复：usage_by_model显示零成本/代币

性能注意事项

环境变量

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP