# Logfire-MCP 分析追踪器
## 基本信息
- Slug: `pydantic-logfire-mcp`
- Source: modelscope
- Publisher: @pydantic/logfire-mcp
- Categories: monitoring / databases
- Hosted: Yes
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@pydantic/logfire-mcp
## 简介
一种模型上下文协议服务器，使大型语言模型能够从 Logfire 检索和分析 OpenTelemetry 的痕迹和指标，支持异常跟踪以及针对遥测数据的自定义 SQL 查询。
## 安装提示

```bash
LOGFIRE_READ_TOKEN=YOUR_READ_TOKEN uvx logfire-mcp
```

## MCP Server 详情

# 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` 安装文档](https://docs.astral.sh/uv/getting-started/installation/)。

如果您已经安装了较旧版本的 `uv`，可能需要通过 `uv self update` 来更新它。

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

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

> [!IMPORTANT]
> Logfire 读取令牌是针对项目的，因此您需要为想要暴露给 Logfire MCP 服务器的具体项目创建一个。

### 手动运行服务器
一旦您安装了 `uv` 并获得了 Logfire 读取令牌，就可以使用 `uvx`（由 `uv` 提供）手动运行 MCP 服务器。

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

```bash
LOGFIRE_READ_TOKEN=YOUR_READ_TOKEN uvx logfire-mcp
```


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

```bash
uvx logfire-mcp --read-token=YOUR_READ_TOKEN
```
> [!NOTE]  
> 如果您正在使用 Cursor、Claude Desktop、Cline 或其他管理您的 MCP 服务器的 MCP 客户端，则**不需要**自己手动运行服务器。下一节将展示如何配置这些客户端以利用 Logfire MCP 服务器。

## 配置知名的 MCP 客户端

### 为 Cursor 配置

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

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


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

### 为 Claude Desktop 配置

添加到您的 Claude 设置中：

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


### 为 Cline 配置

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

```json
{
  "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` 参数：
```bash
uvx logfire-mcp --base-url=https://your-logfire-instance.com
```


2. 设置环境变量：
```bash
LOGFIRE_BASE_URL=https://your-logfire-instance.com uvx logfire-mcp
```


## 示例交互

1. 查找过去一小时内所有跟踪中的异常：
```json
{
  "name": "find_exceptions",
  "arguments": {
    "age": 60
  }
}
```


响应：
```json
[
  {
    "filepath": "app/api.py",
    "count": 12
  },
  {
    "filepath": "app/models.py",
    "count": 5
  }
]
```


2. 获取特定文件中跟踪的异常详情：
```json
{
  "name": "find_exceptions_in_file",
  "arguments": {
    "filepath": "app/api.py",
    "age": 1440
  }
}
```


响应：
```json
[
  {
    "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. 在跟踪上运行自定义查询：
```json
{
  "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 服务器：
   ```bash
   uvx logfire-mcp --read-token=YOUR_TOKEN
   ```

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

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

## 贡献

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

有关其他 MCP 服务器和实现模式的示例，请参阅 [Model Context Protocol servers repository](https://github.com/modelcontextprotocol/servers)。

## 许可证

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