Journald MCP Server

Journald MCP 服务

一个用于访问 systemd 日志的 MCP 服务。

功能

• 列出日志中的 systemd 单元
• 列出日志中的 syslog 标识符
• 获取第一条日志条目的日期和时间
• 按日期时间范围（since/until）筛选日志条目
• 按 systemd 单元或 syslog 标识符筛选
• 按消息内容筛选（不区分大小写的子字符串匹配）
• 解析自然语言日期和时间（例如，“2 hours ago”“yesterday at 3pm”）
• 列出特定时间范围内的单元和标识符

安装

# Install dependencies
uv sync

用法

以非 root 用户身份运行：授予用户 systemd-journal 组访问权限 usermod -aG systemd-journal $USER

使用以下命令运行服务：

uv run server.py [OPTIONS]

CLI 选项

• --transport：要使用的传输协议（stdio、sse 或 streamable-http）。默认值：stdio
• --port：HTTP 传输的监听端口（stdio 传输时忽略）。默认值：3002
• --log-level：日志级别（DEBUG、INFO、WARNING、ERROR、CRITICAL）。默认值：INFO

示例

1. 使用 stdio 传输运行（默认，适用于通过 stdin/stdout 通信的 MCP 客户端）：

   python server.py
   

2. 使用 HTTP 传输并指定自定义端口运行：

   python server.py --transport streamable-http --port 8080
   

3. 使用 SSE 传输运行：

   python server.py --transport sse --port 3000
   

4. 使用调试日志运行：

   python server.py --log-level DEBUG
   

MCP 集成

该服务提供以下 MCP 资源和工具：

资源

• journal://units：列出日志中的唯一 systemd 单元（所有可访问时间范围）
• journal://syslog-identifiers：列出日志中的唯一 syslog 标识符（所有可访问时间范围）
• journal://first-entry-datetime：获取日志中第一条条目的日期和时间
• journal://units/{since}/{until}：列出指定时间范围内的唯一 systemd 单元
• journal://syslog-identifiers/{since}/{until}：列出指定时间范围内的唯一 syslog 标识符

工具

• get_journal_entries：按日期和时间筛选日志条目

  • 参数：since（可选）、until（可选）、unit（可选）、identifier（可选）、message_contains（可选）、limit（默认值：100）
  • 返回：包含时间戳、单元、标识符和消息的条目列表
  • 示例：获取过去 2 小时内包含“error”的日志：since="2 hours ago", message_contains="error"

• get_recent_logs：获取过去 N 分钟内的最新日志

  • 参数：minutes（默认值：60）、unit（可选）、limit（默认值：50）
  • 返回：格式化后的最新日志消息字符串

日期和时间输入格式

该服务通过 dateparser 库解析自然语言日期和时间。支持的格式包括：

• 相对时间：“2 hours ago”“yesterday at 3pm”“last week”“now”
• 绝对时间：“2024-01-15 14:30”“2024-01-15T14:30:00”
• 混合格式：“today at 9am”“tomorrow 3pm”

所有时间均按 UTC 解释，并以便于阅读的格式返回：“YYYY-MM-DD HH:MM:SS UTC”

开发

本项目使用：

• Python 3.12+
• MCP FastMCP
• systemd-python 访问日志
• Click 提供 CLI 界面
• dateparser 解析自然语言日期和时间

项目结构

journald-mcp-server/
├── journald_mcp_server/     # Main package
│   ├── __init__.py
│   ├── server.py           # MCP server implementation
│   └── datetime_utils.py   # Datetime parsing and formatting utilities
├── tests/                  # Test suite
│   ├── __init__.py
│   └── test_server.py
├── server.py              # Entry point wrapper
├── pyproject.toml
└── README.md

运行测试

python -m pytest tests/