Splunk MCP（モデルコンテキストプロトコル）ツール

Splunk Enterprise/Cloud を自然言語で操作するための FastMCP ベースのツールです。このツールは、直感的なインターフェースを通じて Splunk データの検索、KV ストアの管理、Splunk リソースへのアクセスを行うための一連の機能を提供します。

動作モード

このツールは次の 3 つのモードで動作します。

1. SSEモード（デフォルト）

   • サーバー送信イベントベースの通信

   • リアルタイムの双方向インタラクション

   • ウェブベースのMCPクライアントに適しています

   • 引数が指定されていない場合のデフォルトモード

   • /sseエンドポイント経由のアクセス

2. APIモード

   • RESTful APIエンドポイント

   • /api/v1エンドポイントプレフィックス経由でアクセス

   • python splunk_mcp.py apiから始める

3. STDIOモード

   • 標準入出力ベースの通信

   • Claude Desktopおよびその他のMCPクライアントと互換性があります

   • AIアシスタントとの直接統合に最適

   • python splunk_mcp.py stdioから始める

Related MCP server: MCP Server for Splunk

特徴

• Splunk Search : 自然言語クエリでSplunk検索を実行する

• インデックス管理: Splunk インデックスの一覧表示と検査

• ユーザー管理: Splunk ユーザーの表示と管理

• KVストア操作: KVストアコレクションの作成、一覧表示、管理

• 非同期サポート: パフォーマンス向上のため、async/await パターンで構築されています

• 詳細なログ記録: 絵文字インジケーターによる包括的なログ記録で視認性が向上します

• SSL 構成: さまざまなセキュリティ要件に対応する柔軟な SSL 検証オプション

• 強化されたデバッグ: トラブルシューティングのための詳細な接続とエラーのログ記録

• 包括的なテスト: すべての主要な機能をカバーするユニットテスト

• エラー処理: 適切なステータスコードによる堅牢なエラー処理

• SSE準拠:MCP SSE仕様に完全準拠

利用可能なMCPツール

MCP インターフェース経由では次のツールが利用できます。

ツール管理

• リストツール

  • 利用可能なすべてのMCPツールとその説明およびパラメータを一覧表示します。

健康チェック

• ヘルスチェック

  • 接続を確認するために利用可能なSplunkアプリのリストを返します

• ピン

  • MCP サーバーが稼働していることを確認するためのシンプルな ping エンドポイント

ユーザー管理

• 現在のユーザー

  • 現在認証されているユーザーに関する情報を返します

• リストユーザー

  • すべてのユーザーとその役割のリストを返します

インデックス管理

• リストインデックス

  • アクセス可能なすべてのSplunkインデックスのリストを返します

• インデックス情報を取得する

  • 特定のインデックスに関する詳細情報を返します

  • パラメータ: index_name (文字列)

• インデックスとソースタイプ

  • インデックスとそのソースタイプの包括的なリストを返します

検索

• 検索_splunk

  • Splunk検索クエリを実行する

  • パラメータ:

    • search_query (文字列): Splunk検索文字列

    • earliest_time（文字列、オプション）: 検索ウィンドウの開始時刻

    • Latest_time（文字列、オプション）: 検索ウィンドウの終了時刻

    • max_results (整数、オプション): 返される結果の最大数

• 保存した検索リスト

  • Splunkインスタンスに保存された検索のリストを返します

KVストア

• list_kvstore_collections

  • すべてのKVストアコレクションを一覧表示します

• kvstoreコレクションを作成する

  • 新しいKVストアコレクションを作成します

  • パラメータ: collection_name (文字列)

• 削除_kvstore_コレクション

  • 既存のKVストアコレクションを削除します

  • パラメータ: collection_name (文字列)

SSEエンドポイント

SSE モードで実行する場合、次のエンドポイントが利用できます。

• /sse : SSE接続情報をテキスト/イベントストリーム形式で返します

  • SSE接続に関するメタデータを提供します

  • メッセージエンドポイントのURLが含まれています

  • プロトコルと機能の情報を提供します

• /sse/messages : メインのSSEストリームエンドポイント

  • ハートビートなどのシステムイベントをストリーミングする

  • 永続的な接続を維持

  • 適切にフォーマットされたSSEイベントを送信します

• /sse/health : SSEモードのヘルスチェックエンドポイント

  • SSE形式でステータスとバージョン情報を返します

エラー処理

MCP 実装には一貫したエラー処理が含まれます。

• 無効な検索コマンドまたは不正なリクエスト

• 権限が不十分です

• リソースが見つかりません

• 無効な入力検証

• 予期しないサーバーエラー

• Splunk サーバーとの接続の問題

すべてのエラー応答には、エラーを説明する詳細なメッセージが含まれます。

前提条件

• Python 3.10以上

• 依存管理のための詩

• Splunk Enterprise/Cloudインスタンス

• 必要な権限を持つ適切なSplunk認証情報

インストール

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

1. リポジトリをクローンします。

git clone <repository-url>
cd splunk-mcp

2. Poetry を使用して依存関係をインストールします。

poetry install

3. サンプル環境ファイルをコピーして設定を構成します。

cp .env.example .env

4. Splunk の資格情報を使用して.envファイルを更新します。

SPLUNK_HOST=your_splunk_host
SPLUNK_PORT=8089
SPLUNK_USERNAME=your_username
SPLUNK_PASSWORD=your_password
SPLUNK_SCHEME=https
VERIFY_SSL=true
FASTMCP_LOG_LEVEL=INFO

オプション2: Dockerのインストール

1. 最新のイメージをプルします:

docker pull livehybrid/splunk-mcp:latest

2. 上記のように.envファイルを作成するか、環境変数を直接使用します。

3. Docker Compose を使用して実行します。

docker-compose up -d

または Docker を直接使用します:

docker run -i \
  --env-file .env \
  livehybrid/splunk-mcp

使用法

ローカル使用

このツールは 3 つのモードで実行できます。

1. SSE モード (MCP クライアントのデフォルト):

# Start in SSE mode (default)
poetry run python splunk_mcp.py
# or explicitly:
poetry run python splunk_mcp.py sse

# Use uvicorn directly:
SERVER_MODE=api poetry run uvicorn splunk_mcp:app --host 0.0.0.0 --port 8000 --reload

3. STDIO モード:

poetry run python splunk_mcp.py stdio

Dockerの使用

このプロジェクトは、新しいdocker compose (V2) コマンドと従来のdocker-compose (V1) コマンドの両方をサポートしています。以下の例ではV2構文を使用していますが、どちらもサポートされています。

1. SSE モード (デフォルト):

docker compose up -d mcp

2. API モード:

docker compose run --rm mcp python splunk_mcp.py api

3. STDIO モード:

docker compose run -i --rm mcp python splunk_mcp.py stdio

Dockerを使ったテスト

このプロジェクトには、Docker の専用テスト環境が含まれています。

1. すべてのテストを実行します。

./run_tests.sh --docker

2. 特定のテスト コンポーネントを実行します。

# Run only the MCP server
docker compose up -d mcp

# Run only the test container
docker compose up test

# Run both with test results
docker compose up --abort-on-container-exit

テスト結果は./test-resultsディレクトリに保存されます。

Docker開発のヒント

1. 建物画像:

# Build both images
docker compose build

# Build specific service
docker compose build mcp
docker compose build test

2. ログの表示:

# View all logs
docker compose logs

# Follow specific service logs
docker compose logs -f mcp

3. デバッグ:

# Run with debug mode
DEBUG=true docker compose up mcp

# Access container shell
docker compose exec mcp /bin/bash

注意: Docker Compose V1 を使用している場合は、上記のコマンドでdocker compose docker-composeに置き換えてください。

セキュリティノート

1. 環境変数:

• .envファイルをコミットしない

• .env.exampleテンプレートとして使用する

• 本番環境ではDocker secretsの使用を検討する

2. SSL検証:

• 本番環境ではVERIFY_SSL=trueが推奨されます

• 開発/テスト用に無効にすることができます

• 環境変数で設定する

3. ポート露出：

• 必要なポートのみを公開する

• 可能な場合は内部 Docker ネットワークを使用する

• 生産現場でのネットワークセキュリティを考慮する

環境変数

次の環境変数を設定します。

• SPLUNK_HOST : Splunkホストアドレス

• SPLUNK_PORT : Splunk管理ポート（デフォルト: 8089）

• SPLUNK_USERNAME : Splunkユーザー名

• SPLUNK_PASSWORD : Splunkのパスワード

• SPLUNK_SCHEME : 接続スキーム（デフォルト: https）

• VERIFY_SSL : SSL検証を有効/無効にする（デフォルト: true）

• FASTMCP_LOG_LEVEL : ログレベル（デフォルト: INFO）

• SERVER_MODE : uvicorn 使用時のサーバーモード (sse、api、stdio)

SSL設定

このツールは柔軟な SSL 検証オプションを提供します。

1. デフォルト（セキュア）モード：

VERIFY_SSL=true

• 完全なSSL証明書検証

• ホスト名検証が有効

• 実稼働環境に推奨

2. リラックスモード：

VERIFY_SSL=false

• SSL証明書の検証が無効になっています

• ホスト名検証が無効

• テストや自己署名証明書に便利

テスト

このプロジェクトには、pytest を使用した包括的なテスト カバレッジと、カスタム MCP クライアントを使用したエンドツーエンドのテストが含まれています。

テストの実行

基本的なテスト実行:

poetry run pytest

カバレッジレポートの場合:

poetry run pytest --cov=splunk_mcp

詳細出力の場合:

poetry run pytest -v

エンドツーエンドのSSEテスト

このプロジェクトには、ライブ SSE エンドポイントに接続してすべてのツールをテストするカスタム MCP クライアント テスト スクリプトが含まれています。

# Test all tools
python test_endpoints.py

# Test specific tools
python test_endpoints.py health_check list_indexes

# List all available tools
python test_endpoints.py --list

このスクリプトは、次の機能により MCP クライアントとして機能します。

1. /sseエンドポイントに接続してメッセージURLを取得する

2. ツール呼び出しをメッセージエンドポイントに送信する

3. SSEイベントを処理してツールの結果を抽出する

4. 期待される形式に対する結果の検証

これにより、実際の MCP クライアントで使用される SSE インターフェイスの現実的なテストが提供されます。

テスト構造

このプロジェクトでは、3 つの補完的なテスト手法を使用します。

1. MCP 統合テスト( tests/test_api.py ) :

   • mcp.call_tool()を通じて MCP ツール インターフェースをテストします。

   • FastMCPで適切なツール登録を検証

   • 正しい応答形式とデータ構造を保証する

   • MCPインターフェースレベルでのエラー処理を検証します

   • **注:**このファイルは、目的をよりよく反映するために、理想的にはtest_mcp.pyに名前を変更する必要があります。

2. 直接関数テスト( tests/test_endpoints_pytest.py ) :

   • Splunk 機能を直接テストします (MCP レイヤーをバイパス)

   • 関数の実装の詳細をより包括的にカバーします

   • エッジケース、パラメータのバリエーション、エラー処理をテストします

   • SSL構成、接続パラメータ、タイムアウトのテストが含まれています

   • 効率的なテストカバレッジのためにパラメータ化されたテストを使用する

3. エンドツーエンドの MCP クライアント テスト( test_endpoints.py ) :

   • SSEエンドポイントに接続する実際のMCPクライアントのように動作します

   • 接続からツールの呼び出し、応答の解析までの完全なフローをテストします

   • 実際のSSEプロトコル実装を検証する

   • 実際のパラメータを使用してライブサーバーでツールをテストします

4. 構成テスト( tests/test_config.py ) :

   • 環境変数の解析のテスト

   • SSL検証設定

   • 接続パラメータの検証

テストツール

テストは以下をサポートします:

• pytest-asyncio による非同期テスト

• pytest-cov によるカバレッジレポート

• pytest-mock によるモック

• パラメータ化テスト

• 接続タイムアウトテスト

トラブルシューティング

接続の問題

1. 基本的な接続:

• このツールは基本的なTCP接続テストを実行します

• ポート8089にアクセスできるかどうかを確認する

• ネットワークルーティングとファイアウォールを確認する

2. SSLの問題:

• SSLエラーが表示される場合は、 VERIFY_SSL=falseを設定してみてください。

• 証明書の有効性と信頼チェーンを確認する

• ホスト名が証明書と一致することを確認する

3. 認証の問題:

• Splunkの資格情報を確認する

• ユーザー権限を確認する

• アカウントがロックされていないことを確認する

4. デバッグ:

• 詳細なログを取得するには、 FASTMCP_LOG_LEVEL=DEBUGを設定します。

• 特定のエラーメッセージについては接続ログを確認してください

• SSL構成メッセージを確認する

5. SSE 接続の問題:

• SSEエンドポイントが/sse経由でアクセス可能であることを確認する

• 適切なコンテンツタイプヘッダーを確認する

• ブラウザ開発者ツールを使用してSSE接続を検査する

クロード・インテグレーション

クロードデスクトップ構成

Splunk MCPをClaude Desktopと統合するには、SSEモードまたはSTDIOモードのいずれかを使用するように設定する必要があります。claude_desktop_config.jsonに以下の設定claude_desktop_config.json追加してください。

STDIO モード (デスクトップに推奨)

{
  "mcpServers": {
    "splunk": {
      "command": "poetry",
      "env": {
        "SPLUNK_HOST": "your_splunk_host",
        "SPLUNK_PORT": "8089",
        "SPLUNK_USERNAME": "your_username",
        "SPLUNK_PASSWORD": "your_password",
        "SPLUNK_SCHEME": "https",
        "VERIFY_SSL": "false"
      },
      "args": [
          "--directory",
          "/path/to/splunk-mcp",
          "run",
          "python",
          "splunk_mcp.py",
          "stdio"
      ]
    }
  }
}

SSEモード

{
  "mcpServers": {
    "splunk": {
      "command": "poetry",
      "env": {
        "SPLUNK_HOST": "your_splunk_host",
        "SPLUNK_PORT": "8089",
        "SPLUNK_USERNAME": "your_username",
        "SPLUNK_PASSWORD": "your_password",
        "SPLUNK_SCHEME": "https",
        "VERIFY_SSL": "false",
        "FASTMCP_PORT": "8001",
        "DEBUG": "true"
      },
      "args": [
          "--directory",
          "/path/to/splunk-mcp",
          "run",
          "python",
          "splunk_mcp.py",
          "sse"
      ]
    }
  }
}

クロードとの使用

設定が完了すると、Claude を介して自然言語で Splunk と対話できるようになります。例:

1. 利用可能なインデックスを一覧表示します。

What Splunk indexes are available?

2. Splunk データを検索:

Search Splunk for failed login attempts in the last 24 hours

3. システムの健全性を取得します。

Check the health of the Splunk system

4. KV ストアを管理します。

List all KV store collections

MCP ツールは自動的に Claude で使用可能になり、自然言語コマンドを通じてこれらの操作を実行できるようになります。

ライセンス

[ここにライセンスを入力してください]

謝辞

• FastMCPフレームワーク

• Python 用 Splunk SDK

• 構成管理のためのPython分離

• SSE実装のためのSSE Starlette