Splunk MCP-Tool (Model Context Protocol)

Ein FastMCP-basiertes Tool für die Interaktion mit Splunk Enterprise/Cloud über natürliche Sprache. Dieses Tool bietet eine Reihe von Funktionen zum Durchsuchen von Splunk-Daten, Verwalten von KV-Speichern und Zugriff auf Splunk-Ressourcen über eine intuitive Benutzeroberfläche.

Betriebsarten

Das Tool arbeitet in drei Modi:

1. SSE-Modus (Standard)

   • Server-Sent Events-basierte Kommunikation

   • Bidirektionale Interaktion in Echtzeit

   • Geeignet für webbasierte MCP-Clients

   • Standardmodus, wenn keine Argumente angegeben sind

   • Zugriff über /sse -Endpunkt

2. API-Modus

   • RESTful-API-Endpunkte

   • Zugriff über das Endpunktpräfix /api/v1

   • Beginnen Sie mit python splunk_mcp.py api

3. STDIO-Modus

   • Standardmäßige Eingabe-/Ausgabe-basierte Kommunikation

   • Kompatibel mit Claude Desktop und anderen MCP-Clients

   • Ideal für die direkte Integration mit KI-Assistenten

   • Beginnen Sie mit python splunk_mcp.py stdio

Related MCP server: MCP Server for Splunk

Merkmale

• Splunk-Suche : Führen Sie Splunk-Suchen mit Abfragen in natürlicher Sprache aus

• Indexverwaltung : Splunk-Indizes auflisten und prüfen

• Benutzerverwaltung : Splunk-Benutzer anzeigen und verwalten

• KV Store Operations : Erstellen, Auflisten und Verwalten von KV Store-Sammlungen

• Asynchrone Unterstützung : Erstellt mit Asynchron-/Wartemustern für bessere Leistung

• Detaillierte Protokollierung : Umfassende Protokollierung mit Emoji-Indikatoren für bessere Sichtbarkeit

• SSL-Konfiguration : Flexible SSL-Verifizierungsoptionen für unterschiedliche Sicherheitsanforderungen

• Verbessertes Debugging : Detaillierte Verbindungs- und Fehlerprotokollierung zur Fehlerbehebung

• Umfassende Tests : Unit-Tests, die alle wichtigen Funktionen abdecken

• Fehlerbehandlung : Robuste Fehlerbehandlung mit entsprechenden Statuscodes

• SSE-Konformität : Vollständig konform mit der MCP SSE-Spezifikation

Verfügbare MCP-Tools

Über die MCP-Schnittstelle stehen folgende Tools zur Verfügung:

Werkzeugverwaltung

• list_tools

  • Listet alle verfügbaren MCP-Tools mit ihren Beschreibungen und Parametern auf

Gesundheitscheck

• Gesundheitscheck

  • Gibt eine Liste der verfügbaren Splunk-Apps zurück, um die Konnektivität zu überprüfen

• Klingeln

  • Einfacher Ping-Endpunkt zur Überprüfung, ob der MCP-Server aktiv ist

Benutzerverwaltung

• aktueller_Benutzer

  • Gibt Informationen über den aktuell authentifizierten Benutzer zurück

• Benutzerliste

  • Gibt eine Liste aller Benutzer und ihrer Rollen zurück

Indexverwaltung

• Listenindizes

  • Gibt eine Liste aller zugänglichen Splunk-Indizes zurück

• get_index_info

  • Gibt detaillierte Informationen zu einem bestimmten Index zurück

  • Parameter: index_name (Zeichenfolge)

• Indizes und Quelltypen

  • Gibt eine umfassende Liste der Indizes und ihrer Quelltypen zurück

Suchen

• Suche_splunk

  • Führt eine Splunk-Suchabfrage aus

  • Parameter:

    • search_query (Zeichenfolge): Splunk-Suchzeichenfolge

    • earliest_time (Zeichenfolge, optional): Startzeit für das Suchfenster

    • latest_time (Zeichenfolge, optional): Endzeit für das Suchfenster

    • max_results (Ganzzahl, optional): Maximale Anzahl der zurückzugebenden Ergebnisse

• Liste gespeicherter Suchen

  • Gibt eine Liste der gespeicherten Suchen in der Splunk-Instanz zurück

KV Store

• Liste_kvstore_sammlungen

  • Listet alle KV-Store-Kollektionen auf

• Erstellen Sie eine KVStore-Sammlung

  • Erstellt eine neue KV-Store-Kollektion

  • Parameter: collection_name (Zeichenfolge)

• delete_kvstore_collection

  • Löscht eine vorhandene KV-Store-Sammlung

  • Parameter: collection_name (Zeichenfolge)

SSE-Endpunkte

Beim Ausführen im SSE-Modus sind die folgenden Endpunkte verfügbar:

• /sse : Gibt SSE-Verbindungsinformationen im Text-/Ereignisstromformat zurück

  • Stellt Metadaten zur SSE-Verbindung bereit

  • Enthält die URL für den Nachrichtenendpunkt

  • Bietet Protokoll- und Fähigkeitsinformationen

• /sse/messages : Der Hauptendpunkt des SSE-Streams

  • Streamt Systemereignisse wie Heartbeats

  • Hält die Verbindung dauerhaft aufrecht

  • Sendet ordnungsgemäß formatierte SSE-Ereignisse

• /sse/health : Integritätsprüfungsendpunkt für den SSE-Modus

  • Gibt Status- und Versionsinformationen im SSE-Format zurück

Fehlerbehandlung

Die MCP-Implementierung beinhaltet eine konsistente Fehlerbehandlung:

• Ungültige Suchbefehle oder fehlerhafte Anfragen

• Unzureichende Berechtigungen

• Ressource nicht gefunden

• Validierung ungültiger Eingaben

• Unerwartete Serverfehler

• Verbindungsprobleme mit dem Splunk-Server

Alle Fehlerantworten enthalten eine detaillierte Meldung, die den Fehler erklärt.

Voraussetzungen

• Python 3.10 oder höher

• Poesie für das Abhängigkeitsmanagement

• Splunk Enterprise/Cloud-Instanz

• Entsprechende Splunk-Anmeldeinformationen mit den erforderlichen Berechtigungen

Installation

Option 1: Lokale Installation

1. Klonen Sie das Repository:

git clone <repository-url>
cd splunk-mcp

2. Installieren Sie Abhängigkeiten mit Poetry:

poetry install

3. Kopieren Sie die Beispielumgebungsdatei und konfigurieren Sie Ihre Einstellungen:

cp .env.example .env

4. Aktualisieren Sie die .env Datei mit Ihren Splunk-Anmeldeinformationen:

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

Option 2: Docker-Installation

1. Rufen Sie das neueste Bild ab:

docker pull livehybrid/splunk-mcp:latest

2. Erstellen Sie Ihre .env Datei wie oben beschrieben oder verwenden Sie Umgebungsvariablen direkt.

3. Mit Docker Compose ausführen:

docker-compose up -d

Oder direkt mit Docker:

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

Verwendung

Lokale Nutzung

Das Tool kann in drei Modi ausgeführt werden:

1. SSE-Modus (Standard für MCP-Clients):

# 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-Modus:

poetry run python splunk_mcp.py stdio

Docker-Nutzung

Das Projekt unterstützt sowohl die neuen Befehle docker compose “ (V2) als auch docker-compose (V1). Die folgenden Beispiele verwenden die Syntax von V2, aber beide werden unterstützt.

1. SSE-Modus (Standard):

docker compose up -d mcp

2. API-Modus:

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

3. STDIO-Modus:

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

Testen mit Docker

Das Projekt umfasst eine dedizierte Testumgebung in Docker:

1. Führen Sie alle Tests aus:

./run_tests.sh --docker

2. Führen Sie bestimmte Testkomponenten aus:

# 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

Die Testergebnisse sind im Verzeichnis ./test-results verfügbar.

Tipps zur Docker-Entwicklung

1. Gebäudebilder :

# Build both images
docker compose build

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

2. Protokolle anzeigen :

# View all logs
docker compose logs

# Follow specific service logs
docker compose logs -f mcp

3. Debuggen :

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

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

Hinweis: Wenn Sie Docker Compose V1 verwenden, ersetzen Sie in den obigen Befehlen docker compose durch docker-compose .

Sicherheitshinweise

1. Umgebungsvariablen :

• Übernehmen Sie niemals .env Dateien

• Verwenden Sie .env.example als Vorlage

• Erwägen Sie die Verwendung von Docker-Geheimnissen für die Produktion

2. SSL-Verifizierung :

• VERIFY_SSL=true empfohlen für die Produktion

• Kann für Entwicklung/Tests deaktiviert werden

• Konfigurieren über Umgebungsvariablen

3. Hafenlage :

• Nur die erforderlichen Ports offen legen

• Verwenden Sie nach Möglichkeit das interne Docker-Netzwerk

• Berücksichtigen Sie die Netzwerksicherheit in der Produktion

Umgebungsvariablen

Konfigurieren Sie die folgenden Umgebungsvariablen:

• SPLUNK_HOST : Ihre Splunk-Hostadresse

• SPLUNK_PORT : Splunk-Verwaltungsport (Standard: 8089)

• SPLUNK_USERNAME : Ihr Splunk-Benutzername

• SPLUNK_PASSWORD : Ihr Splunk-Passwort

• SPLUNK_SCHEME : Verbindungsschema (Standard: https)

• VERIFY_SSL : SSL-Verifizierung aktivieren/deaktivieren (Standard: true)

• FASTMCP_LOG_LEVEL : Protokollierungsebene (Standard: INFO)

• SERVER_MODE : Servermodus (sse, api, stdio) bei Verwendung von uvicorn

SSL-Konfiguration

Das Tool bietet flexible SSL-Verifizierungsoptionen:

1. Standardmodus (Sicherer Modus) :

VERIFY_SSL=true

• Vollständige SSL-Zertifikatsüberprüfung

• Hostnamenüberprüfung aktiviert

• Empfohlen für Produktionsumgebungen

2. Entspannter Modus :

VERIFY_SSL=false

• SSL-Zertifikatsüberprüfung deaktiviert

• Hostnamenüberprüfung deaktiviert

• Nützlich zum Testen oder für selbstsignierte Zertifikate

Testen

Das Projekt umfasst eine umfassende Testabdeckung mit pytest und End-to-End-Tests mit einem benutzerdefinierten MCP-Client:

Ausführen von Tests

Grundlegende Testausführung:

poetry run pytest

Mit Berichterstattung über die Berichterstattung:

poetry run pytest --cov=splunk_mcp

Mit ausführlicher Ausgabe:

poetry run pytest -v

End-to-End-SSE-Tests

Das Projekt umfasst ein benutzerdefiniertes MCP-Client-Testskript, das eine Verbindung zum Live-SSE-Endpunkt herstellt und alle Tools testet:

# 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

Dieses Skript fungiert als MCP-Client, indem es:

1. Herstellen einer Verbindung zum /sse -Endpunkt, um die Nachrichten-URL abzurufen

2. Senden von Toolaufrufen an den Nachrichtenendpunkt

3. Verarbeiten der SSE-Ereignisse zum Extrahieren von Toolergebnissen

4. Validieren der Ergebnisse anhand der erwarteten Formate

Dies ermöglicht praxisnahe Tests der SSE-Schnittstelle, wie sie von einem tatsächlichen MCP-Client verwendet würde.

Teststruktur

Das Projekt verwendet drei sich ergänzende Testansätze:

1. MCP-Integrationstests ( tests/test_api.py ) :

   • Testet die MCP-Tools-Schnittstelle über mcp.call_tool()

   • Überprüft die ordnungsgemäße Werkzeugregistrierung mit FastMCP

   • Stellt das richtige Antwortformat und die richtige Datenstruktur sicher

   • Validiert die Fehlerbehandlung auf MCP-Schnittstellenebene

   • Hinweis: Diese Datei sollte idealerweise in test_mcp.py umbenannt werden, um ihren Zweck besser widerzuspiegeln

2. Direkte Funktionstests ( tests/test_endpoints_pytest.py ) :

   • Testet Splunk-Funktionen direkt (unter Umgehung der MCP-Schicht)

   • Bietet eine umfassendere Abdeckung der Details der Funktionsimplementierung

   • Testet Randfälle, Parametervariationen und Fehlerbehandlung

   • Beinhaltet Tests für SSL-Konfiguration, Verbindungsparameter und Timeouts

   • Verwendet parametrisiertes Testen für eine effiziente Testabdeckung

3. End-to-End-MCP-Clienttests ( test_endpoints.py ) :

   • Verhält sich wie ein echter MCP-Client, der eine Verbindung zum SSE-Endpunkt herstellt

   • Testet den gesamten Ablauf von der Verbindung über den Tool-Aufruf bis hin zur Antwortanalyse

   • Validiert die tatsächliche Implementierung des SSE-Protokolls

   • Testet Tools mit realen Parametern gegen den Live-Server

4. Konfigurationstests ( tests/test_config.py ) :

   • Tests zum Parsen von Umgebungsvariablen

   • SSL-Verifizierungseinstellungen

   • Validierung der Verbindungsparameter

Testwerkzeuge

Die Tests unterstützen:

• Asynchrones Testen mit pytest-asyncio

• Abdeckungsberichte mit pytest-cov

• Mocking mit pytest-mock

• Parametrisiertes Testen

• Testen des Verbindungstimeouts

Fehlerbehebung

Verbindungsprobleme

1. Grundlegende Konnektivität :

• Das Tool führt nun einen grundlegenden TCP-Konnektivitätstest durch

• Überprüfen Sie, ob Port 8089 erreichbar ist

• Überprüfen Sie das Netzwerk-Routing und die Firewalls

2. SSL-Probleme :

• Wenn SSL-Fehler auftreten, versuchen Sie VERIFY_SSL=false festzulegen.

• Überprüfen Sie die Gültigkeit des Zertifikats und die Vertrauenskette

• Überprüfen, ob der Hostname mit dem Zertifikat übereinstimmt

3. Authentifizierungsprobleme :

• Überprüfen der Splunk-Anmeldeinformationen

• Überprüfen Sie die Benutzerberechtigungen

• Stellen Sie sicher, dass das Konto nicht gesperrt ist

4. Debuggen :

• Setzen Sie FASTMCP_LOG_LEVEL=DEBUG für detaillierte Protokolle

• Überprüfen Sie die Verbindungsprotokolle auf bestimmte Fehlermeldungen

• Überprüfen der SSL-Konfigurationsmeldungen

5. SSE-Verbindungsprobleme :

• Überprüfen Sie, ob der SSE-Endpunkt über /sse erreichbar ist.

• Überprüfen Sie, ob die Inhaltstyp-Header korrekt sind.

• Verwenden Sie Browser-Entwicklertools, um SSE-Verbindungen zu überprüfen

Claude Integration

Claude Desktop-Konfiguration

Sie können Splunk MCP in Claude Desktop integrieren, indem Sie es für den SSE- oder STDIO-Modus konfigurieren. Fügen Sie Ihrer claude_desktop_config.json die folgende Konfiguration hinzu:

STDIO-Modus (empfohlen für Desktop)

{
  "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-Modus

{
  "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"
      ]
    }
  }
}

Verwendung mit Claude

Nach der Konfiguration können Sie über Claude in natürlicher Sprache mit Splunk interagieren. Beispiele:

1. Liste der verfügbaren Indizes:

What Splunk indexes are available?

2. Splunk-Daten durchsuchen:

Search Splunk for failed login attempts in the last 24 hours

3. Systemzustand abrufen:

Check the health of the Splunk system

4. KV-Stores verwalten:

List all KV store collections

Die MCP-Tools stehen Claude automatisch zur Verfügung, sodass er diese Vorgänge über Befehle in natürlicher Sprache ausführen kann.

Lizenz

[Ihre Lizenz hier]

Danksagung

• FastMCP-Framework

• Splunk SDK für Python

• Python-Decouple für das Konfigurationsmanagement

• SSE Starlette für die SSE-Implementierung