JSON Logs MCP Server

JSON Logs MCP サーバー

Claude Desktop（または任意の MCP クライアント）が JSON 形式のログファイルを読み取り、分析できるようにする Model Context Protocol（MCP）サーバーです。このサーバーでは、構造化されたログデータの検索、フィルタリング、集計、分析を行うツールを利用できます。

機能

• 📁 ログファイルの閲覧 - JSON 形式のログファイルを一覧表示し、読み取ります
• 🔍 検索とフィルタリング - レベル、モジュール、関数、メッセージ内容、時間範囲でログをクエリします
• 📊 データの集計 - さまざまな条件でログをグループ化し、分析します
• 📈 統計情報 - ログデータに関する包括的な統計情報を取得します
• 🚀 高速かつ効率的 - 大容量のログファイルを処理できるよう最適化されています

前提条件

• Python 3.11 以降
• Claude Desktop（または別の MCP クライアント）

インストール

1. このリポジトリをクローンします：

git clone https://github.com/mfreeman451/json-logs-mcp-server.git
cd json-logs-mcp-server

2. 仮想環境を作成します：

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. パッケージをインストールします：

pip install -e .

4. ラッパースクリプトを作成します：

cat > run-json-logs-server.sh << 'EOF'
#!/bin/bash
cd "$(dirname "$0")"
source .venv/bin/activate
exec python json_logs_mcp_server.py
EOF
chmod +x run-json-logs-server.sh

設定

ログディレクトリの設定

デフォルトでは、サーバーは実行場所を基準とした ./logs ディレクトリ内のログを検索します。環境変数を設定するか、コードを編集して変更できます：

オプション 1：環境変数

export MCP_JSON_LOGS_DIR="/path/to/your/logs"

Claude Desktop の設定

Claude Desktop の設定ファイルにサーバーを追加します：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "json-logs": {
      "command": "/absolute/path/to/run-json-logs-server.sh",
      "args": [],
      "env": {
        "MCP_JSON_LOGS_DIR": "/path/to/your/logs"
      }
    }
  }
}

重要：ラッパースクリプトには絶対パスを使用してください。

ログ形式

サーバーは、1 行につき 1 つの JSON オブジェクトを含む JSON ログファイルを想定しています。各ログエントリには、次のフィールドを含めてください：

{
  "timestamp": "2024-01-15T10:30:45.123456",
  "level": "INFO",
  "message": "User authentication successful",
  "module": "auth.handler",
  "function": "authenticate_user",
  "line": 42
}

必須フィールド：

• timestamp - ISO 形式のタイムスタンプ
• level - ログレベル（DEBUG、INFO、WARNING、ERROR、CRITICAL）
• message - ログメッセージ
• module - モジュール名
• function - 関数名
• line - 行番号

ログファイルのサンプル

サーバーをテストするには、次の内容で example.log という名前のファイルを作成します：

{"timestamp": "2024-01-15T10:30:45.123456", "level": "INFO", "message": "Application started successfully", "module": "main", "function": "startup", "line": 15}
{"timestamp": "2024-01-15T10:30:46.234567", "level": "DEBUG", "message": "Loading configuration from config.json", "module": "config.loader", "function": "load_config", "line": 42}
{"timestamp": "2024-01-15T10:30:47.345678", "level": "INFO", "message": "Database connection established", "module": "db.connection", "function": "connect", "line": 78}
{"timestamp": "2024-01-15T10:31:02.456789", "level": "WARNING", "message": "Rate limit approaching: 85% of quota used", "module": "api.ratelimit", "function": "check_limits", "line": 156}
{"timestamp": "2024-01-15T10:32:15.567890", "level": "ERROR", "message": "Failed to authenticate user: Invalid credentials", "module": "auth.handler", "function": "authenticate_user", "line": 203}
{"timestamp": "2024-01-15T10:32:16.678901", "level": "INFO", "message": "Retry attempt 1/3 for user authentication", "module": "auth.handler", "function": "retry_auth", "line": 215}
{"timestamp": "2024-01-15T10:33:45.789012", "level": "CRITICAL", "message": "Database connection lost: Connection timeout", "module": "db.connection", "function": "health_check", "line": 92}
{"timestamp": "2024-01-15T10:33:46.890123", "level": "INFO", "message": "Attempting database reconnection", "module": "db.connection", "function": "reconnect", "line": 105}
{"timestamp": "2024-01-15T10:33:48.901234", "level": "INFO", "message": "Database connection restored", "module": "db.connection", "function": "reconnect", "line": 112}
{"timestamp": "2024-01-15T10:35:22.012345", "level": "DEBUG", "message": "Cache hit for key: user_session_abc123", "module": "cache.manager", "function": "get", "line": 67}

Python ロガーの設定例

必要な形式で出力するよう Python ロガーを設定する方法は次のとおりです：

import logging
import json
from datetime import datetime

class JSONFormatter(logging.Formatter):
    def format(self, record):
        log_obj = {
            "timestamp": datetime.fromtimestamp(record.created).isoformat(),
            "level": record.levelname,
            "message": record.getMessage(),
            "module": record.module,
            "function": record.funcName,
            "line": record.lineno
        }
        return json.dumps(log_obj)

# Configure logger
logger = logging.getLogger()
handler = logging.FileHandler('app.log')
handler.setFormatter(JSONFormatter())
logger.addHandler(handler)
logger.setLevel(logging.INFO)

# Example usage
logger.info("Application started")
logger.error("Something went wrong")

利用可能なツール

1. list_log_files

メタデータとともに、利用可能なすべてのログファイルを一覧表示します。

Claude での使用例：

• 「すべてのログファイルを一覧表示して」
• 「利用可能なログを見せて」

2. query_logs

ログエントリを検索してフィルタリングします。

パラメーター：

• files - 検索対象のファイル一覧（省略可。デフォルトではすべて）
• level - ログレベルでフィルタリング
• module - モジュール名でフィルタリング
• function - 関数名でフィルタリング
• message_contains - メッセージ内容を検索
• start_time - 開始時刻のフィルター（ISO 形式）
• end_time - 終了時刻のフィルター（ISO 形式）
• limit - 結果の最大数（デフォルト：100）

Claude での使用例：

• 「今日のすべての ERROR ログを表示して」
• 「'database connection' を含むログを探して」
• 「過去 1 時間の auth モジュールのエラーを表示して」
• 「認証の失敗を検索して」

3. aggregate_logs

指定した条件でログデータを集計します。

パラメーター：

• files - 分析対象のファイル（省略可）
• group_by - グループ化の条件：「level」、「module」、「function」、または「hour」

Claude での使用例：

• 「ログをレベル別にグループ化して」
• 「最も多くログを生成しているモジュールを教えて」
• 「時間別にログの分布を分析して」
• 「ログレベルの内訳を教えて」

4. get_log_stats

ログファイルに関する包括的な統計情報を取得します。

Claude での使用例：

• 「ログの統計情報を表示して」
• 「ログ全体の概要を教えて」
• 「エラーは合計でいくつありますか？」

使用例

設定が完了したら、Claude Desktop を通じてログを操作できます：

例 1：エラーの検索

You: "Show me all ERROR and CRITICAL logs from the last hour"
Claude: I'll search for ERROR and CRITICAL level logs from the last hour...
[Uses query_logs tool with level and time filters]

例 2：パターンの分析

You: "Which module is generating the most warnings?"
Claude: Let me analyze the distribution of WARNING logs by module...
[Uses query_logs with level filter, then aggregate_logs grouped by module]

例 3：問題のデバッグ

You: "Find all database connection errors and show me what happened right before them"
Claude: I'll search for database connection errors and their context...
[Uses query_logs to find specific errors and surrounding log entries]

スタンドアロンでの実行

テスト（MCP Inspector やその他の MCP クライアント）用に、サーバーをスタンドアロンで実行することもできます：

# With stdio transport (default)
python json_logs_mcp_server.py

トラブルシューティング

サーバーが起動しない

• Python 3.8 以降がインストールされていることを確認してください：python3 --version
• すべての依存関係がインストールされていることを確認してください：pip install -e .
• ログディレクトリが存在し、.log ファイルが含まれていることを確認してください

「spawn python ENOENT」エラー

• 設定では python の代わりに python3 を使用してください
• 完全な絶対パスを指定してラッパースクリプトを使用してください
• ラッパースクリプトが実行可能であることを確認してください：chmod +x run-json-logs-server.sh

「Module not found」エラー

• 仮想環境を有効にするラッパースクリプトを使用していることを確認してください
• venv に依存関係がインストールされていることを確認してください：source .venv/bin/activate && pip list
• 依存関係を再インストールしてください：pip install -e .

ログが見つからない

• 設定されたディレクトリにログファイルが存在することを確認してください
• ログファイルの拡張子が .log であることを確認してください（*.log* に一致するファイルが見つかります）
• ログファイルが正しい JSON 形式（1 行につき JSON オブジェクト 1 つ）であることを確認してください
• 上記のサンプルログファイルを使って試してください

Claude にツールが表示されない

• 設定を変更した後、Claude Desktop を再起動してください
• Claude Desktop の「Connect Apps」セクションを確認してください
• Claude の開発者コンソールでエラーメッセージを確認してください
• Claude の UI でサーバーが「Connected」と表示されていることを確認してください

デバッグのヒント

• エラーメッセージを確認できるよう、サーバーを手動で実行してください：./run-json-logs-server.sh
• サーバーの出力を確認してください：stdio 経由で実行すると、診断メッセージが stderr に表示されます
• まずは上記のサンプルデータを使って、シンプルなログファイルでテストしてください
• JSON 形式を確認してください：各行は、必須フィールドをすべて含む有効な JSON である必要があります

パフォーマンスに関する考慮事項

• サーバーはログファイルを一括ではなく、必要に応じて読み込みます
• 大きなログファイル（>100MB）は処理に時間がかかる場合があります
• クエリで limit パラメーターを使用して、結果のサイズを調整してください
• パフォーマンスを維持するため、ログファイルのローテーションを検討してください

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

ライセンス

MIT ライセンスの詳細については、LICENSE ファイルを参照してください