Seq MCP

🚀 SEQ MCP Server

SEQ MCP Server 是一个 MCP（模型上下文协议）服务器，它使大语言模型（LLMs）能够从 SEQ 结构化日志记录服务器查询和分析日志。该服务器为日志管理和分析提供了强大的功能，帮助用户更高效地处理和理解日志数据。

✨ 主要特性

• 搜索事件：使用强大的 SEQ 过滤语法查询日志。
• 获取事件详情：检索特定日志事件的完整信息。
• 分析日志：对一段时间内的日志模式进行统计分析。
• 列出信号：访问 SEQ 中配置的已保存搜索/信号。
• 健康检查：监控 SEQ 服务器状态。

📦 安装指南

选项 1：使用 Docker（推荐）

# 使用 GitHub 容器注册表
docker pull ghcr.io/roeej/seq-mcp:latest

# 或者使用 Docker Hub
docker pull roeej/seq-mcp:latest

选项 2：从源代码安装

git clone https://github.com/RoeeJ/seq-mcp.git
cd seq-mcp
npm install
npm run build

📚 详细文档

配置

环境变量

*如果您的 SEQ 实例启用了身份验证，则必需。

设置说明

1. 复制示例环境文件：

cp .env.example .env

2. 使用您的 SEQ 服务器详细信息编辑 .env 文件：

SEQ_URL=http://your-seq-server:5341
SEQ_API_KEY=your-api-key-here

与 Claude Desktop 一起使用

macOS

1. 打开 Claude Desktop 设置。
2. 导航到“开发者”→“编辑配置”。
3. 添加 SEQ 服务器配置：

{
  "mcpServers": {
    "seq": {
      "command": "node",
      "args": ["/absolute/path/to/seq-mcp/dist/index.js"],
      "env": {
        "SEQ_URL": "http://localhost:5341",
        "SEQ_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windows

1. 打开 Claude Desktop 设置。
2. 导航到“开发者”→“编辑配置”。
3. 添加 SEQ 服务器配置：

{
  "mcpServers": {
    "seq": {
      "command": "node.exe",
      "args": ["C:\\path\\to\\seq-mcp\\dist\\index.js"],
      "env": {
        "SEQ_URL": "http://localhost:5341",
        "SEQ_API_KEY": "your-api-key-here"
      }
    }
  }
}

与 Claude Code 一起使用

选项 1：使用 .env 文件

1. 在项目根目录创建一个 .env 文件：

SEQ_URL=http://localhost:5341
SEQ_API_KEY=your-api-key-here

2. 添加到您的 Claude Code MCP 配置中：

{
  "seq": {
    "command": "node",
    "args": ["/path/to/seq-mcp/dist/index.js"]
  }
}

选项 2：直接使用环境变量

{
  "seq": {
    "command": "node",
    "args": ["/path/to/seq-mcp/dist/index.js"],
    "env": {
      "SEQ_URL": "http://localhost:5341",
      "SEQ_API_KEY": "your-api-key-here",
      "SEQ_DEFAULT_LIMIT": "200",
      "SEQ_TIMEOUT": "60000"
    }
  }
}

选项 3：使用系统环境变量

在您的 shell 中设置环境变量：

# macOS/Linux - 添加到 ~/.bashrc 或 ~/.zshrc
export SEQ_URL="http://localhost:5341"
export SEQ_API_KEY="your-api-key-here"

# Windows PowerShell
$env:SEQ_URL = "http://localhost:5341"
$env:SEQ_API_KEY = "your-api-key-here"

然后使用简单的配置：

{
  "seq": {
    "command": "node",
    "args": ["/path/to/seq-mcp/dist/index.js"]
  }
}

从 SEQ 获取 API 密钥

1. 在 Web 浏览器中打开您的 SEQ 实例。
2. 导航到“设置”→“API 密钥”。
3. 点击“添加 API 密钥”。
4. 提供一个标题（例如，“MCP 服务器”）。
5. 设置适当的权限（通常“读取”就足够了）。
6. 复制生成的 API 密钥。

在 Claude 中的示例用法

配置完成后，您可以自然地查询日志：

"Show me all error logs from the last hour"
"Find logs containing 'timeout' errors"
"Analyze the log patterns for my API service"
"What are the most common errors in the last 24 hours?"
"Get details for event ID abc123"

可用工具

search_events

使用过滤器搜索事件：

- query: SEQ 过滤语法（例如，"Level = 'Error'" 或 "@Message like '%failed%'"）
- count: 结果数量（1 - 1000）
- fromDate/toDate: ISO 日期字符串
- level: 按日志级别过滤

get_event

按 ID 获取特定事件的详细信息。

analyze_logs

分析日志模式：

- query: 可选的 SEQ 过滤器
- timeRange: 1h、6h、24h、7d 或 30d
- groupBy: 用于分组结果的属性名称

list_signals

列出 SEQ 中所有配置的信号（已保存的搜索）。

check_health

检查 SEQ 服务器的健康状态。

故障排除

连接问题

1. 验证 SEQ 是否正在运行：

curl http://localhost:5341/api/health

2. 检查 API 密钥权限：确保您的 API 密钥具有“读取”权限。
3. 网络/防火墙：确保 MCP 服务器可以访问您的 SEQ 实例。
4. 超时错误：对于大型查询，增加 SEQ_TIMEOUT。

常见错误

• "Unauthorized"：检查您的 API 密钥是否正确。
• "Connection refused"：验证 SEQ_URL 并确保 SEQ 正在运行。
• "Timeout"：查询可能过于复杂，尝试添加更具体的过滤器。

开发

# 在开发模式下运行
npm run dev

# 运行测试
npm test

# 代码检查
npm run lint

# 类型检查
npm run typecheck

SEQ 查询示例

• Level = 'Error' - 所有错误日志
• @Message like '%timeout%' - 包含“timeout”的消息
• Application = 'MyApp' and Level in ['Warning', 'Error'] - MyApp 的警告和错误
• @Timestamp > Now() - 1h - 最近一小时的事件
• StatusCode >= 400 - HTTP 错误
• Environment = 'Production' and ResponseTime > 1000 - 生产环境中的慢请求
• UserId = '12345' - 特定用户的所有日志
• @Exception is not null - 所有包含异常的日志

高级配置

使用 Docker

如果 SEQ 在 Docker 中运行：

{
  "seq": {
    "command": "node",
    "args": ["/path/to/seq-mcp/dist/index.js"],
    "env": {
      "SEQ_URL": "http://host.docker.internal:5341",
      "SEQ_API_KEY": "your-api-key"
    }
  }
}

使用远程 SEQ

对于云托管的 SEQ 实例：

{
  "seq": {
    "command": "node",
    "args": ["/path/to/seq-mcp/dist/index.js"],
    "env": {
      "SEQ_URL": "https://seq.yourcompany.com",
      "SEQ_API_KEY": "your-api-key",
      "SEQ_TIMEOUT": "60000"
    }
  }
}

Docker 使用

运行容器

# 基本用法
docker run --rm \
  -e SEQ_URL=http://host.docker.internal:5341 \
  -e SEQ_API_KEY=your-api-key \
  ghcr.io/roeej/seq-mcp:latest

# 使用所有环境变量
docker run --rm \
  -e SEQ_URL=http://your-seq-server:5341 \
  -e SEQ_API_KEY=your-api-key \
  -e SEQ_DEFAULT_LIMIT=200 \
  -e SEQ_TIMEOUT=60000 \
  ghcr.io/roeej/seq-mcp:latest

与 Claude Desktop（Docker）一起使用

添加到您的 Claude Desktop 配置中：

{
  "mcpServers": {
    "seq": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "SEQ_URL=http://host.docker.internal:5341",
        "-e", "SEQ_API_KEY=your-api-key",
        "ghcr.io/roeej/seq-mcp:latest"
      ]
    }
  }
}

与 Claude Code（Docker）一起使用

{
  "seq": {
    "command": "docker",
    "args": [
      "run",
      "--rm",
      "-i",
      "-e", "SEQ_URL=http://your-seq-server:5341",
      "-e", "SEQ_API_KEY=your-api-key",
      "ghcr.io/roeej/seq-mcp:latest"
    ]
  }
}

Docker Compose 示例

创建一个 docker-compose.yml 文件：

version: '3.8'

services:
  seq-mcp:
    image: ghcr.io/roeej/seq-mcp:latest
    environment:
      - SEQ_URL=http://seq:5341
      - SEQ_API_KEY=${SEQ_API_KEY}
    networks:
      - seq-network

  seq:
    image: datalust/seq:latest
    ports:
      - "5341:5341"
    environment:
      - ACCEPT_EULA=Y
    networks:
      - seq-network

networks:
  seq-network:
    driver: bridge

架构

• MCP 服务器：处理工具定义和请求路由。
• SEQ 客户端：管理与 SEQ 的 API 通信。
• 类型安全：使用 Zod 验证的完整 TypeScript。
• 错误处理：优雅降级和有意义的错误消息。

安全

• API 密钥从不记录或暴露。
• 所有请求在执行前都会进行验证。
• 对长时间运行的查询提供超时保护。
• 只读操作（不修改日志）。
• 支持 HTTP 和 HTTPS 连接。

CI/CD 管道

本项目使用 GitHub Actions 进行持续集成和部署：

• CI：每次推送和 PR 时运行，以确保代码质量。

  • 使用 ESLint 进行代码检查。
  • 使用 TypeScript 进行类型检查。
  • 使用 Vitest 进行单元测试。
  • 多版本 Node.js 测试（18.x、20.x）。

• Docker 发布：

  • 在主分支上自动构建并发布到 GitHub 容器注册表。
  • 在版本标签上发布到 Docker Hub。
  • 多平台构建（linux/amd64、linux/arm64）。
  • 语义化版本标签。

创建发布

1. 标记您的发布：

git tag v1.0.0
git push origin v1.0.0

2. GitHub Action 将自动执行以下操作：

• 构建多平台 Docker 镜像。
• 推送到 ghcr.io/roeej/seq-mcp:1.0.0。
• 推送到 dockerhub/roeej/seq-mcp:1.0.0（需要设置密钥）。

所需的 GitHub 密钥

对于 Docker Hub 发布（可选）：

• DOCKERHUB_USERNAME：您的 Docker Hub 用户名。
• DOCKERHUB_TOKEN：Docker Hub 访问令牌。

注意：GitHub 容器注册表（ghcr.io）发布使用存储库的 GITHUB_TOKEN 自动工作，无需额外设置。

贡献

1. 分叉仓库。
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)。
3. 提交您的更改 (git commit -m 'Add some amazing feature')。
4. 推送到分支 (git push origin feature/amazing-feature)。
5. 打开一个拉取请求。

📄 许可证

本项目采用 MIT 许可证。