Logfire MCP Server

此代码库包含一个模型上下文协议（MCP）服务器，以及可以访问您发送到 Logfire 的 OpenTelemetry 跟踪和指标的工具。

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

可用工具

• 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@latest

或使用 --read-token 标志：

uvx logfire-mcp@latest --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@latest", "--read-token=YOUR-TOKEN"]
    }
  }
}

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

配置 Claude Desktop

在您的 Claude 设置中添加：

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

配置 Cline

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

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

配置 VS Code

确保您已 在 VS Code 中启用 MCP 支持。

在项目的根目录下创建一个 .vscode/mcp.json 文件：

{
  "servers": {
    "logfire": {
      "type": "stdio",
      "command": "uvx", // 或绝对路径 /path/to/uvx
      "args": ["logfire-mcp@latest"],
      "env": {
        "LOGFIRE_READ_TOKEN": "YOUR_TOKEN",
        "LOGFIRE_BASE_URL": "https://api-eu.pydantic.dev" // 选择正确的 base url
      }
    }
  }
}

自定义 - Base URL

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

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

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

2. 设置环境变量：

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

示例交互

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

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

{
  "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@latest --read-token=YOUR_TOKEN
   

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

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

贡献

我们欢迎对 Logfire MCP 服务器做出贡献，无论是添加新的跟踪分析工具、增强指标查询功能还是改进文档，您的意见都非常有价值。

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

许可证

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