SEQ MCP Server

SEQ MCP服务器

MCP（模型上下文协议）服务器，使LLM能够从SEQ结构化日志服务器查询和分析日志。

特性

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

先决条件

• Node.js 18+
• 访问SEQ服务器实例
• SEQ API密钥（可选，但建议用于安全实例）

安装

选项1：使用Docker（推荐）

# Using GitHub Container Registry
docker pull ghcr.io/roeej/seq-mcp:latest

# Or using 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

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

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

使用Claude Desktop

macOS

1. 打开克劳德桌面设置
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"
      }
    }
  }
}

视窗

1. 打开克劳德桌面设置
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代码

选项1：使用.env文件

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

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

1. 添加到您的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 - add to ~/.bashrc or ~/.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"

可用工具

搜索事件

使用筛选器搜索事件：

- query: SEQ filter syntax (e.g., "Level = 'Error'" or "@Message like '%failed%'")
- count: Number of results (1-1000)
- fromDate/toDate: ISO date strings
- level: Filter by log level

get_event

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

分析日志

分析日志模式：

- query: Optional SEQ filter
- timeRange: 1h, 6h, 24h, 7d, or 30d
- groupBy: Property name to group results

list_信号

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

健康检查

检查SEQ服务器运行状况。

故障排除

连接问题

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

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

1. 检查API密钥权限：确保您的API密钥具有“读取”权限

1. 网络/防火墙：确保MCP服务器可以访问您的SEQ实例

1. 超时错误：增加 SEQ_TIMEOUT 对于大型查询

常见错误

• “未经授权”：检查您的API密钥是否正确
• “连接被拒绝”：验证SEQ_URL和SEQ是否正在运行
• “超时”：查询可能太复杂，请尝试添加更具体的筛选器

发展

# Run in development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Type check
npm run typecheck

SEQ查询示例

• Level = 'Error' -所有错误日志
• @Message like '%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使用

运行容器

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

# With all environment variables
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编写示例

创建一个 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客户端：管理API与SEQ的通信
• 类型安全：带有Zod验证的完整TypeScript
• 错误处理：优雅的降级和有意义的错误消息

安全

• API密钥从未被记录或公开
• 所有请求在执行前都经过验证
• 长时间运行的查询的超时保护
• 只读操作（无日志修改）
• 支持HTTP和HTTPS连接

CI/CD管道

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

• CI公司：在每次推送和PR中运行，以确保代码质量

- 用ESLint打毛 - 使用TypeScript进行类型检查 - 使用Vitest进行单元测试 - 多版本Node.js测试（18.x，20.x）

• Docker Publishing:

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

创建发布

1. 标记您的释放：

   git tag v1.0.0
   git push origin v1.0.0

1. 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. 打开拉取请求

许可证

麻省理工学院