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

1. 设置环境变量：

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

1. 获取特定文件中跟踪的异常详情：

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

1. 在跟踪上运行自定义查询：

{
  "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 服务器和实现模式的示例，请参阅 Model Context Protocol servers repository。

许可证

Logfire MCP 根据 MIT 许可证获得许可。这意味着你可以自由地使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。