Journald MCP Server

🚀 Journald MCP Server

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

🚀 クイックスタート

Journald MCP Serverは、systemdのジャーナルログにアクセスするためのMCPサーバーです。以下に、インストールと使用方法を説明します。

✨ 主な機能

• ジャーナルログからsystemdユニットを一覧表示する
• ジャーナルログからsyslog識別子を一覧表示する
• 最初のジャーナルエントリの日時を取得する
• 日時範囲（since/until）でジャーナルエントリをフィルタリングする
• systemdユニットまたはsyslog識別子でフィルタリングする
• メッセージ内容でフィルタリングする（大文字小文字を区別しない部分文字列一致）
• 自然言語の日時解析（例：「2 hours ago」、「yesterday at 3pm」）
• 特定の時間範囲内のユニットと識別子を一覧表示する

📦 インストール

# 依存関係をインストールする
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 for journal access
• Click for CLI interface
• dateparser for natural language datetime parsing

プロジェクト構造

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/