MCP Server Graylog

🚀 mcp-server-graylog

このプロジェクトは、Graylogのログ検索用のModel Context Protocol (MCP) サーバーです。絶対/相対タイムスタンプでログを検索し、ストリームでフィルタリングし、Claude Desktopから直接本番環境の問題をデバッグできます。

🚀 クイックスタート

このサーバーを使用することで、Graylogのログを絶対または相対タイムスタンプで検索し、ストリームでフィルタリングできます。Claude Desktopから直接本番環境の問題をデバッグするのに最適です。

✨ 主な機能

• ✅ 絶対タイムスタンプ検索 - 正確な時間範囲で特定のエラーをデバッグ
• ✅ 相対タイムスタンプ検索 - 最近のログ（過去N秒）を検索
• ✅ ストリーム探索 - 利用可能なすべてのストリーム/アプリケーションをリスト表示
• ✅ システムヘルスチェック - Graylogへの接続を確認
• ✅ 包括的な検証 - ISO 8601タイムスタンプ、クエリ構文、ストリームID
• ✅ 明確なエラーメッセージ - 認証、ネットワーク、APIの問題に対する実行可能なエラー
• ✅ タイムアウト処理 - 30秒のタイムアウトでハングを防止
• ✅ 本番環境対応 - 54のテスト、コード品質スコア9.2/10

📦 インストール

オプション1: npxを使用する（推奨）

# インストール不要 - npxで直接使用
npx mcp-server-graylog

オプション2: グローバルインストール

npm install -g mcp-server-graylog

オプション3: ローカルインストール

# リポジトリをクローン
git clone https://github.com/Pranavj17/mcp-server-graylog.git
cd mcp-server-graylog

# 依存関係をインストール
npm install

📚 ドキュメント

設定

Claude Desktopの設定

Claude Desktopの設定ファイルに追加します。

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

npxを使用する場合（推奨）

{
  "mcpServers": {
    "graylog": {
      "command": "npx",
      "args": ["-y", "mcp-server-graylog"],
      "env": {
        "BASE_URL": "https://graylog.example.com",
        "API_TOKEN": "your_api_token_here"
      }
    }
  }
}

ローカルインストールを使用する場合

{
  "mcpServers": {
    "graylog": {
      "command": "node",
      "args": ["/path/to/mcp-server-graylog/src/index.js"],
      "env": {
        "BASE_URL": "https://graylog.example.com",
        "API_TOKEN": "your_api_token_here"
      }
    }
  }
}

環境変数

Graylog APIトークンの取得方法

1. GraylogのWebインターフェースにログイン
2. System → Users に移動
3. 自分のユーザーを選択
4. Edit tokens をクリック
5. 読み取り権限を持つ新しいトークンを作成
6. トークンの値をコピー

利用可能なツール

1. search_logs_absolute

絶対タイムスタンプ（from/to）を使用してログを検索します。監視ツールやエラー追跡システムからの特定のタイムスタンプでエラーをデバッグするのに最適です。

• パラメーター:
  • query (必須): Elasticsearch構文を使用した検索クエリ
  • from (必須): ISO 8601形式の開始タイムスタンプ
  • to (必須): ISO 8601形式の終了タイムスタンプ
  • streamId (オプション): 結果をフィルタリングするストリームID
  • limit (オプション): 最大結果数（デフォルト: 50、最大: 1000）
• 例:

{
  "query": "\"/api/v1/registrations\" AND \"PUT\"",
  "from": "2025-10-23T10:00:00.000Z",
  "to": "2025-10-23T11:00:00.000Z",
  "streamId": "646221a5bd29672a6f0246d8",
  "limit": 100
}

2. search_logs_relative

相対的な時間範囲（例: 過去15分）を使用してログを検索します。最近のログ分析に便利です。

• パラメーター:
  • query (必須): Elasticsearch構文を使用した検索クエリ
  • rangeSeconds (オプション): 秒単位の時間範囲（デフォルト: 900 = 15分、最大: 86400 = 24時間）
  • streamId (オプション): 結果をフィルタリングするストリームID
  • limit (オプション): 最大結果数（デフォルト: 50、最大: 1000）
• 例:

{
  "query": "level:ERROR",
  "rangeSeconds": 3600,
  "limit": 100
}

3. list_streams

利用可能なすべてのGraylogストリーム（アプリケーション）をリスト表示します。フィルタリング用のストリームIDを見つけるのに使用します。

• パラメーター: なし
• 戻り値:

{
  "total": 3,
  "streams": [
    {
      "id": "646221a5bd29672a6f0246d8",
      "title": "clientmaster",
      "description": "Client Master application logs",
      "disabled": false
    }
  ]
}

4. get_system_info

Graylogのシステム情報とヘルスステータスを取得します。接続を確認し、サーバーのバージョンをチェックします。

• パラメーター: なし
• 戻り値:

{
  "version": "5.1.0",
  "codename": "graylog",
  "cluster_id": "abc123",
  "is_processing": true,
  "timezone": "UTC"
}

クエリ例

エラーを検索する

level:ERROR

特定のエンドポイントを検索する

"/api/v1/registrations" AND "PUT"

HTTPステータスコードを検索する

status:500
status:>=400

ユーザーアクションを検索する

user_id:12345 AND action:login

遅いリクエストを検索する

duration_ms:>1000

例外を検索する

exception:NullPointerException

複数の条件を組み合わせる

level:ERROR AND source:nexus AND message:*timeout*

ワイルドカードを使用して検索する

message:*connection refused*

フィールドの存在による検索

_exists_:error_code

一般的なユースケース

1. 本番環境のエラーをデバッグする

監視システムからタイムスタンプ付きのエラーが発生した場合:

1. 監視ツールからエラーのタイムスタンプをコピー
2. search_logs_absoluteを±5分のウィンドウで使用
3. アプリケーションストリームでフィルタリング
4. ログから根本原因を見つける

2. 最近のデプロイを監視する

デプロイ後:

1. 過去15分のsearch_logs_relativeを使用
2. level:ERRORを検索
3. 新しいエラーが導入されていないことを確認

3. APIの失敗を調査する

APIエンドポイントが失敗した場合:

1. エンドポイントパスを検索: "/api/v1/endpoint"
2. ステータスコードでフィルタリング: status:>=400
3. エラーパターンを確認

エラーメッセージ

サーバーは明確で実行可能なエラーメッセージを提供します。

トラブルシューティング

サーバーが起動しない場合

# Claude Desktop設定内のBASE_URLとAPI_TOKENが設定されていることを確認
# Claude Desktopのログを確認:
# macOS: ~/Library/Logs/Claude/mcp*.log
# Windows: %APPDATA%\Claude\logs\mcp*.log

# Graylogのアクセス可能性を確認
curl -u "YOUR_API_TOKEN:token" https://graylog.example.com/api/system

認証エラーが発生する場合

• Graylog内でAPIトークンが読み取り権限を持っていることを確認
• トークン形式: トークン値をユーザー名、"token" をパスワードとして使用
• トークンが期限切れになっていないことを確認

結果が返されない場合

• list_streams ツールを使用してストリームIDが正しいことを確認
• タイムスタンプ範囲にデータが含まれていることを確認
• クエリを * に簡素化してデータが存在するかどうかを確認
• ストリームが無効になっていないことを確認

統合テストが失敗する場合

# 統合テスト用の環境変数を設定
export INTEGRATION_TESTS=true
export BASE_URL=https://graylog.example.com
export API_TOKEN=your_token_here

# 統合テストを実行
npm run test:integration

開発

前提条件

• Node.js >= 18.0.0
• npm >= 8.0.0
• Graylogインスタンスへのアクセス（統合テスト用）

開発ワークフロー

# 依存関係をインストール
npm install

# 開発モードで実行（自動リロード）
npm run dev

# テストを実行
npm test

# ウォッチモードでテストを実行
npm run test:watch

# ユニットテストのみを実行
npm run test:unit

# 統合テストを実行（Graylogインスタンスが必要）
INTEGRATION_TESTS=true BASE_URL=https://graylog.example.com API_TOKEN=xxx npm run test:integration

# 構文をチェック
npm run lint

プロジェクト構造

mcp-server-graylog/
├── src/
│   └── index.js           # メインサーバーの実装（429行）
├── test/
│   ├── helpers.test.js    # ヘルパー関数のテスト（14テスト）
│   ├── validation.test.js # 入力検証のテスト（24テスト）
│   ├── mcp-protocol.test.js # MCPプロトコルのテスト（16テスト）
│   └── integration.test.js  # 統合テスト（7テスト）
├── example-config.json    # Claude Desktopの設定例
├── CONTRIBUTING.md        # コントリビュートガイドライン
├── CHANGELOG.md          # バージョン履歴
└── package.json         # npmの設定

テストの実行

# すべてのテストを実行（54テスト）
npm test

# 期待される出力:
# tests 54
# pass 54
# fail 0

アーキテクチャ

単一のファイル（429行）でのシンプルで焦点のあるアーキテクチャ:

• 設定と検証 - 環境変数のチェック
• ヘルパー関数 - ISO 8601の検証、エラーのフォーマット
• MCPサーバーのセットアップ - 標準のMCPプロトコルの実装
• ツール定義 - 明確なスキーマを持つ4つのツール
• ツールの実装 - クリーンで検証済みの関数
• サーバーの起動 - 検証後に接続

設計原則:

• ✓ シンプルで保守しやすい
• ✓ 1つのファイルで、理解しやすい
• ✓ 関心事の明確な分離
• ✓ 包括的なエラー処理
• ✓ 境界での入力検証
• ✓ 一貫したレスポンス形式

コントリビュート

コントリビューションは歓迎されます！ガイドラインについては CONTRIBUTING.md を参照してください。

• クイックスタート:
  1. リポジトリをフォーク
  2. 機能ブランチを作成
  3. 変更に対するテストを追加
  4. すべてのテストが通過することを確認 (npm test)
  5. プルリクエストを送信

変更履歴

バージョン履歴とリリースノートについては CHANGELOG.md を参照してください。

セキュリティ

• 機密データには環境変数を使用（ハードコードしない）
• 基本認証が適切に実装されている
• 入力検証によりインジェクション攻撃を防止
• タイムアウトによりハングするリクエストを防止
• エラーメッセージには機密情報が漏れない

セキュリティバウンティを報告するには、GitHubでプライベートなセキュリティアドバイザリを作成してください。

📄 ライセンス

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

リンク

• npmパッケージ
• GitHubリポジトリ
• イシュートラッカー
• Model Context Protocol
• Graylogドキュメント

謝辞

• @modelcontextprotocol/sdk で構築
• MCPコミュニティからのインスピレーション
• すべてのコントリビューターに感謝！

❤️ Claude Desktopコミュニティのために作成されました

質問やサポートが必要な場合は、GitHubでイシューを開いてください