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。您可以通过以下方式覆盖此设置：

1. 使用 --base-url 参数：

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

2. 设置环境变量：

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

示例交互

1. 查找最近一小时追踪中的所有异常：

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

响应：

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

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

{
  "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"
  }
]

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

{
  "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
  }
}

Claude 的示例问题

1. "过去一小时内所有服务中追踪中发生了哪些异常？"
2. "显示文件 'app/api.py' 中的最近错误及其追踪上下文"
3. "过去 24 小时内每个服务中有多少错误？"
4. "我的追踪中最常见的异常类型是什么，按服务名称分组？"
5. "获取追踪和指标的 OpenTelemetry 模式"
6. "查找昨天的所有错误并显示它们的追踪上下文"

入门指南

1. 首先，从以下地址获取 Logfire 读取令牌： https://logfire.pydantic.dev/-/redirect/latest-project/settings/read-tokens

2. 运行 MCP 服务器：

   uvx logfire-mcp --read-token=YOUR_TOKEN
   

3. 使用上述配置示例配置您首选的客户端（Cursor、Claude Desktop 或 Cline）

4. 开始使用 MCP 服务器分析您的 OpenTelemetry 追踪和指标！

贡献

我们欢迎贡献以帮助改进 Logfire MCP 服务器。无论您是想添加新的追踪分析工具、增强指标查询功能，还是改进文档，您的贡献都是有价值的。

有关其他 MCP 服务器和实现模式的示例，请参阅 模型上下文协议服务器仓库。

许可证

Logfire MCP 根据 MIT 许可证授权。这意味着您可以自由使用、修改和分发软件，但需遵守 MIT 许可证的条款和条件。