Journald MCP Server

🚀 Journald MCP 服務器

Journald MCP 服務器是一個用於訪問 systemd 日誌的 MCP 服務器，它可以幫助用戶方便地獲取和篩選 systemd 日誌信息。

🚀 快速開始

Journald MCP 服務器可讓你輕鬆訪問和篩選 systemd 日誌。以下是快速上手的步驟：

1. 安裝依賴（見“📦 安裝指南”）。
2. 配置用戶權限（見“💻 使用示例”）。
3. 啟動服務器（見“💻 使用示例”）。

✨ 主要特性

• 從日誌中列出 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。

示例

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 集成

資源

• 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/