Journald MCP Server

Journald MCP サーバー

systemd ジャーナルログにアクセスするための MCP サーバーです。

機能

• ジャーナルログから systemd ユニットを一覧表示
• ジャーナルログから syslog 識別子を一覧表示
• 最初のジャーナルエントリーの日時を取得
• 日時範囲（開始／終了）でジャーナルエントリーをフィルタリング
• 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
• CLI インターフェースに Click
• 自然言語による日時の解析に 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/