使用说明

项目简介

Logfire MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器实现，它充当 LLM 客户端和 Logfire 遥测数据平台之间的桥梁。通过此服务器，LLM 可以安全地访问您在 Logfire 中存储的 OpenTelemetry 追踪 (Traces) 和指标 (Metrics) 数据，从而实现更智能的应用监控、问题诊断和数据分析。

主要功能点

异常分析工具: 提供 'find_exceptions' 和 'find_exceptions_in_file' 工具，帮助 LLM 快速定位和分析应用中的异常情况，例如：
- 统计最近一段时间内各个文件中发生的异常数量。
- 获取特定文件中最近发生的异常的详细信息，包括时间、错误消息、堆栈追踪等。
自定义查询工具: 'arbitrary_query' 工具允许 LLM 执行自定义 SQL 查询，灵活地从 Logfire 数据库中检索和分析遥测数据。
Schema查询工具: 'get_logfire_records_schema' 工具帮助 LLM 获取 Logfire 遥测数据 (records) 的 schema 信息，以便构建更有效的自定义查询。

安装步骤

安装 'uv': 'uv' 用于运行 Logfire MCP 服务器。请参考 uv 安装文档完成安装。如果已安装旧版本 'uv'，建议使用 'uv self update' 命令更新。
获取 Logfire Read Token: Logfire MCP 服务器需要一个只读 (Read) Token 才能访问 Logfire API。请登录 Logfire 项目设置页面，在 "Read Tokens" 部分创建一个新的 Read Token。请务必为需要暴露给 MCP 服务器的项目创建 Token。
运行 MCP 服务器: 使用 'uvx' 命令手动启动 Logfire MCP 服务器。您可以通过环境变量 'LOGFIRE_READ_TOKEN' 或命令行参数 '--read-token' 指定您的 Read Token。

使用环境变量:
```
LOGFIRE_READ_TOKEN=YOUR_READ_TOKEN uvx logfire-mcp
```
使用命令行参数:
```
uvx logfire-mcp --read-token=YOUR_READ_TOKEN
```
注意: 如果您使用 Cursor, Claude Desktop, Cline 等 MCP 客户端，这些客户端会自动管理 MCP 服务器，您无需手动运行服务器。请参考下一节配置客户端。

服务器配置

以下是针对不同 MCP 客户端的 Logfire MCP 服务器配置示例。您需要将这些配置添加到您的 MCP 客户端设置中。

1. Cursor 配置 ('.cursor/mcp.json'):

{
  "mcpServers": {
    "logfire": {
      "command": "uvx", // 启动服务器的命令，这里使用 uvx
      "args": ["logfire-mcp", "--read-token=YOUR-TOKEN"] // 启动参数，包括服务器程序名和 Read Token。请将 YOUR-TOKEN 替换为您在 Logfire 获取的 Read Token
    }
  }
}

注意: Cursor 不支持 'env' 字段配置环境变量，因此需要使用 '--read-token' 命令行参数传递 Read Token。

2. Claude Desktop 配置 (Claude 设置):

{
  "command": ["uvx"], // 启动服务器的命令，这里使用 uvx
  "args": ["logfire-mcp"], // 启动参数，只有服务器程序名
  "type": "stdio", // 通信类型，使用标准输入输出流
  "env": {
    "LOGFIRE_READ_TOKEN": "YOUR_TOKEN" // 通过环境变量传递 Read Token。请将 YOUR_TOKEN 替换为您在 Logfire 获取的 Read Token
  }
}

3. Cline 配置 ('cline_mcp_settings.json'):

{
  "mcpServers": {
    "logfire": {
      "command": "uvx", // 启动服务器的命令，这里使用 uvx
      "args": ["logfire-mcp"], // 启动参数，只有服务器程序名
      "env": {
        "LOGFIRE_READ_TOKEN": "YOUR_TOKEN" // 通过环境变量传递 Read Token。请将 YOUR_TOKEN 替换为您在 Logfire 获取的 Read Token
      },
      "disabled": false, // 是否禁用该服务器，设置为 false 表示启用
      "autoApprove": [] // 自动批准的工具列表，这里为空表示需要手动批准
    }
  }
}

自定义 Base URL: 默认情况下，服务器连接到 Logfire API 的地址是 'https://logfire-api.pydantic.dev'。您可以通过以下方式自定义 Base URL：

使用 '--base-url' 参数:

uvx logfire-mcp --base-url=https://your-logfire-instance.com

设置 'LOGFIRE_BASE_URL' 环境变量:

LOGFIRE_BASE_URL=https://your-logfire-instance.com uvx logfire-mcp

基本使用方法

配置完成后，您可以在支持 MCP 协议的 LLM 客户端中使用 Logfire MCP 服务器提供的工具。以下是一些示例 JSON 请求，您可以将这些请求发送到 MCP 服务器以调用相应的工具：

1. 查询最近一小时内所有异常的文件及数量:

{
  "name": "find_exceptions",
  "arguments": {
    "age": 60 // 查询最近 60 分钟的数据
  }
}

2. 查询指定文件 "app/api.py" 中最近一天内的异常详细信息:

{
  "name": "find_exceptions_in_file",
  "arguments": {
    "filepath": "app/api.py", // 要查询的文件路径
    "age": 1440 // 查询最近 1440 分钟 (24 小时) 的数据
  }
}

3. 执行自定义 SQL 查询，例如查询最近一天内的 ERROR 日志 (需要对 Logfire 数据 Schema 有所了解):

{
  "name": "arbitrary_query",
  "arguments": {
    "query": "SELECT trace_id, message, created_at, attributes->>'service.name' as service FROM records WHERE severity_text = 'ERROR' ORDER BY created_at DESC LIMIT 10", // 自定义 SQL 查询语句
    "age": 1440 // 查询最近 1440 分钟 (24 小时) 的数据
  }
}

4. 获取 Logfire records 表的 Schema 信息:

{
  "name": "get_logfire_records_schema",
  "arguments": {} // 无需参数
}

您可以结合 LLM 的自然语言处理能力，向 LLM 提出类似以下问题，LLM 客户端会自动调用相应的 MCP 工具并返回结果：

"过去一小时内所有服务发生了哪些异常？"
"展示 'app/api.py' 文件中最近的错误，并提供它们的追踪上下文。"
"过去 24 小时内，每个服务分别有多少个错误？"
"我的追踪数据中最常见的异常类型是什么，按服务名称分组？"
"获取追踪和指标的 OpenTelemetry schema。"
"查找昨天所有的错误，并展示它们的追踪上下文。"

关键词