MCP 服务器

Logfire MCP Server

一个模型上下文协议（Model Context Protocol）服务器，它使大型语言模型（LLM）能够从 Logfire 检索和分析 OpenTelemetry 追踪和指标，支持异常跟踪以及针对遥测数据的自定义 SQL 查询。

README

Logfire MCP 服务器

此仓库包含一个模型上下文协议 (MCP) 服务器，其中包含可以访问您已发送到 Logfire 的 OpenTelemetry 追踪和指标的工具。

此 MCP 服务器使 LLM 能够检索您的应用程序的遥测数据、分析分布式追踪，并利用使用 Logfire API 执行的任意 SQL 查询的结果。

可用工具

find_exceptions - 从按文件分组的追踪中获取异常计数
- 必需参数：
  - age (int)：回溯的分钟数（例如，30 表示过去 30 分钟，最长 7 天）
find_exceptions_in_file - 获取有关特定文件中异常的详细追踪信息
- 必需参数：
  - filepath (string)：要分析的文件的路径
  - age (int)：回溯的分钟数（最长 7 天）
arbitrary_query - 在您的 OpenTelemetry 追踪和指标上运行自定义 SQL 查询
- 必需参数：
  - query (string)：要执行的 SQL 查询
  - age (int)：回溯的分钟数（最长 7 天）
get_logfire_records_schema - 获取 OpenTelemetry 模式以帮助进行自定义查询
- 无需参数

设置

安装 `uv`

首先要确保已安装 uv，因为 uv 用于运行 MCP 服务器。

有关安装说明，请参阅 uv 安装文档。

如果您已经安装了旧版本的 uv，则可能需要使用 uv self update 更新它。

获取 Logfire 读取令牌

为了向 Logfire API 发出请求，Logfire MCP 服务器需要一个“读取令牌”。

您可以在 Logfire 的项目设置的“读取令牌”部分下创建一个： https://logfire.pydantic.dev/-/redirect/latest-project/settings/read-tokens

[!IMPORTANT] Logfire 读取令牌是特定于项目的，因此您需要为您要暴露给 Logfire MCP 服务器的特定项目创建一个。

手动运行服务器

安装 uv 并拥有 Logfire 读取令牌后，您可以使用 uvx（由 uv 提供）手动运行 MCP 服务器。

您可以使用 LOGFIRE_READ_TOKEN 环境变量指定您的读取令牌：

LOGFIRE_READ_TOKEN=YOUR_READ_TOKEN uvx logfire-mcp

或者使用 --read-token 标志：

uvx logfire-mcp --read-token=YOUR_READ_TOKEN

[!NOTE] 如果您正在使用 Cursor、Claude Desktop、Cline 或其他为您管理 MCP 服务器的 MCP 客户端，则**不需要**手动运行服务器。下一节将向您展示如何配置这些客户端以使用 Logfire MCP 服务器。

使用知名的 MCP 客户端进行配置

为 Cursor 配置

在您的项目根目录中创建一个 .cursor/mcp.json 文件：

{
  "mcpServers": {
    "logfire": {
      "command": "uvx",
      "args": ["logfire-mcp", "--read-token=YOUR-TOKEN"]
    }
  }
}

Cursor 不接受 env 字段，因此您需要改用 --read-token 标志。

为 Claude Desktop 配置

添加到您的 Claude 设置：

{
  "command": ["uvx"],
  "args": ["logfire-mcp"],
  "type": "stdio",
  "env": {
    "LOGFIRE_READ_TOKEN": "YOUR_TOKEN"
  }
}

为 Cline 配置

添加到 cline_mcp_settings.json 中的 Cline 设置：

{
  "mcpServers": {
    "logfire": {
      "command": "uvx",
      "args": ["logfire-mcp"],
      "env": {
        "LOGFIRE_READ_TOKEN": "YOUR_TOKEN"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

自定义 - 基础 URL

默认情况下，服务器连接到 https://logfire-api.pydantic.dev 上的 Logfire API。您可以通过以下方式覆盖此设置：

使用 --base-url 参数：

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

设置环境变量：

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

示例交互

查找过去一小时内所有服务中的追踪中的所有异常：

{
  "name": "find_exceptions",
  "arguments": {
    "age": 60
  }
}

响应：

[
  {
    "filepath": "app/api.py",
    "count": 12
  },
  {
    "filepath": "app/models.py",
    "count": 5
  }
]

获取有关特定文件中追踪中的异常的详细信息：

{
  "name": "find_exceptions_in_file",
  "arguments": {
    "filepath": "app/api.py",
    "age": 1440
  }
}

响应：

[
  {
    "created_at": "2024-03-20T10:30:00Z",
    "message": "Failed to process request",
    "exception_type": "ValueError",
    "exception_message": "Invalid input format",
    "function_name": "process_request",
    "line_number": "42",
    "attributes": {
      "service.name": "api-service",
      "code.filepath": "app/api.py"
    },
    "trace_id": "1234567890abcdef"
  }
]

在追踪上运行自定义查询：

{
  "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",
    "age": 1440
  }
}