JinDaGe - journald-mcp-server MCP Details

article

README

🚀 Journald MCP 服务器

Journald MCP 服务器是一个用于访问 systemd 日志的 MCP 服务器，它可以帮助用户方便地获取和筛选 systemd 日志信息。

🚀 快速开始

Journald MCP 服务器可让你轻松访问和筛选 systemd 日志。以下是快速上手的步骤：

安装依赖（见“📦 安装指南”）。
配置用户权限（见“💻 使用示例”）。
启动服务器（见“💻 使用示例”）。

✨ 主要特性

从日志中列出 systemd 单元。
从日志中列出系统日志标识符。
获取第一条日志条目的日期和时间。
按日期时间范围（从/到）过滤日志条目。
按 systemd 单元或系统日志标识符过滤。
按消息内容过滤（不区分大小写的子字符串匹配）。
支持自然语言日期时间解析（例如，“2 小时前”、“昨天下午 3 点”）。
列出特定时间范围内的单元和标识符。

📦 安装指南

# 安装依赖
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。

示例

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

python server.py

使用自定义端口的 HTTP 传输：

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

使用 SSE 传输：

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

使用调试日志级别：

python server.py --log-level DEBUG

📚 详细文档

MCP 集成

资源

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

工具

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 小时前”、“昨天下午 3 点”、“上周”、“现在”。
绝对时间：“2024-01-15 14:30”、“2024-01-15T14:30:00”。
混合格式：“今天上午 9 点”、“明天下午 3 点”。所有时间都解释为 UTC 时间，并以人类可读的格式返回：“YYYY-MM-DD HH:MM:SS UTC”。

🔧 技术细节

项目依赖

Python 3.12+
MCP FastMCP
systemd-python 用于日志访问
Click 用于 CLI 接口
dateparser 用于自然语言日期时间解析

项目结构

journald-mcp-server/
├── journald_mcp_server/     # 主包
│   ├── __init__.py
│   ├── server.py           # MCP 服务器实现
│   └── datetime_utils.py   # 日期时间解析和格式化工具
├── tests/                  # 测试套件
│   ├── __init__.py
│   └── test_server.py
├── server.py              # 入口点包装器
├── pyproject.toml
└── README.md

运行测试

python -m pytest tests/

journald-mcp-server