Splunk Model Context Protocol (MCP) Handler

A high-performance, FastMCP-compliant utility designed to interface with Splunk environments (both on-premise Enterprise and Cloud instances) via intuitive, natural language commands. It furnishes a spectrum of functionality for data retrieval, configuration management, and resource access.

Operational Paradigms

The system supports three distinct communication patterns:

1. Server-Sent Events (SSE) Protocol (Default)
2. Utilizes persistent, unidirectional data streaming via SSE.
3. Enables low-latency, real-time data flow.
4. Best suited for web-based frontends consuming MCP data.

5. Activated by default; accessible through the /sse URI.

6. Standard Application Programming Interface (API) Mode

7. Employs conventional HTTP methods for interaction.
8. Endpoints are prefixed under /api/v1.

9. Initiated via: python splunk_mcp.py api

10. Standard Input/Output (STDIO) Mode

11. Communication relies solely on standard terminal I/O streams.
12. Designed for compatibility with desktop AI clients (e.g., Claude Desktop).
13. Initiated via: python splunk_mcp.py stdio

Core Functionalities

• Data Search: Submit complex Splunk Query Language (SPL) statements via plain English.
• Index Inspection: Catalog and retrieve metadata for all configured Splunk indexes.
• Identity Administration: View and manage Splunk user identities and their associated roles.
• KV Store Manipulation: Full CRUD operations for managing Key-Value store collections.
• Asynchronous Design: Architected using modern async/await patterns for optimal throughput.
• Verbose Telemetry: Comprehensive logging system featuring symbolic indicators for clarity.
• TLS Configuration: Adjustable parameters for SSL certificate validation.
• Diagnostic Output: Extensive connection and runtime error tracing for rapid troubleshooting.
• Test Suite: Thorough unit and integration testing covering primary execution paths.
• Resilient Fault Tolerance: Robust error mechanisms returning informative status codes.
• Protocol Conformance: Full adherence to the specified MCP SSE specification standards.

Exposed MCP Tool Set

Functionality is exposed through the following callable modules:

System Utilities

• list_tools
• Enumerates all active MCP tool definitions and their required arguments.

System Status

• health_check
• Pings the Splunk environment, confirming connectivity by listing installed applications.
• ping
• Basic heartbeat endpoint confirming MCP service responsiveness.

User Access Control

• current_user
• Fetches details for the currently authenticated session principal.
• list_users
• Retrieves a complete registry of users and their assigned privileges.

Data Index Management

• list_indexes
• Obtains a roster of all accessible Splunk indexes.
• get_index_info
• Returns granular configuration details for a specified index.
• Arguments: index_name (text)
• indexes_and_sourcetypes
• Provides an aggregate mapping of indexes to their associated data source types.

Query Execution

• search_splunk
• Executes a specified search query against the Splunk backend.
• Arguments:
  • search_query (text): The SPL string to execute.
  • earliest_time (text, optional): Defines the temporal starting boundary.
  • latest_time (text, optional): Defines the temporal ending boundary.
  • max_results (numeric, optional): Caps the quantity of returned records.
• list_saved_searches
• Retrieves definitions for all persistently saved searches.

Key-Value Store Operations

• list_kvstore_collections
• Lists all defined KV store containers.
• create_kvstore_collection
• Initializes a new KV store container.
• Arguments: collection_name (text)
• delete_kvstore_collection
• Permanently removes an existing KV store container.
• Arguments: collection_name (text)

SSE Communication Channels

When operating under the SSE execution model, the following URI routes are active:

• /sse: Establishes the initial connection path.
• Transmits metadata regarding the connection context.
• Specifies the message stream URL.

• Confirms protocol version and supported capabilities.

• /sse/messages: The primary unidirectional data conduit.

• Streams system events, including periodic keep-alive signals (heartbeats).
• Maintains the sustained connection state.

• Dispatches messages conforming strictly to SSE formatting.

• /sse/health: A specialized health endpoint for the SSE service.

• Delivers operational status and software version details within the SSE event format.

Error Reporting Framework

The MCP handler ensures consistent error reporting across all operations:

• Malformed requests or syntactically incorrect search commands.
• Authentication/Authorization failures (insufficient privileges).
• Attempts to access non-existent resources.
• Input data validation failures.
• Unforeseen internal service exceptions.
• Loss of connectivity to the target Splunk server.

Every error outcome includes a descriptive textual explanation of the failure.

Deployment and Setup

Recommended Installation via UV (Rust-based Installer)

UV offers superior performance and dependency resolution compared to traditional methods.

Prerequisites

• Python interpreter version 3.10 or newer.
• UV package manager installed (Refer to the official UV installation guide for setup).

Expedited Setup with UV

1. Obtain Source Code: bash git clone cd splunk-mcp

2. Install Dependencies: bash # Install core runtime dependencies uv sync

# Install core plus development/testing dependencies uv sync --extra dev

1. Execution Commands: bash # Launch in default SSE mode uv run python splunk_mcp.py

# Launch in STDIO mode uv run python splunk_mcp.py stdio

# Launch in API mode uv run python splunk_mcp.py api

Key UV Command Reference

bash

Standard dependency installation

uv sync

Install development dependencies

uv sync --extra dev

Execute the main script

uv run python splunk_mcp.py

Execute test suite

uv run pytest

Execute using a specific Python version (e.g., 3.11)

uv run --python 3.11 python splunk_mcp.py

Add a new library requirement

uv add fastapi

Add a testing dependency

uv add --dev pytest

Update all current dependencies

uv sync --upgrade

Generate standard requirements.txt from pyproject.toml

uv pip compile pyproject.toml -o requirements.txt

Alternative: Poetry Dependency Manager

Poetry users can utilize standard commands:

bash

Install dependencies

poetry install

Execute the application

poetry run python splunk_mcp.py

Alternative: Pip Package Manager

For traditional environments:

bash

Install dependencies from list

pip install -r requirements.txt

Run executable

python splunk_mcp.py

Execution Modalities

The utility operates under three distinct execution environments:

1. SSE (Server-Sent Events) (Default)
2. Leverages persistent, server-pushed data streams.
3. Optimized for interactive MCP client consumption.

4. Invoked implicitly or via python splunk_mcp.py sse.

5. API (RESTful Interface)

6. Provides standard HTTP request/response endpoints.

7. Startup sequence: python splunk_mcp.py api

8. STDIO (Stream-Based)

9. Direct standard I/O channel communication.
10. Primary mode for integration with local CLI tools and AI session managers.
11. Startup sequence: python splunk_mcp.py stdio

Execution Scenarios

Local Execution

1. SSE mode (Primary MCP client interaction): bash

Start via Poetry (default)

poetry run python splunk_mcp.py

Or explicitly specify mode:

poetry run python splunk_mcp.py sse

Direct startup using ASGI server (if running as API server):

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

1. STDIO mode: bash poetry run python splunk_mcp.py stdio

Containerized Execution (Docker)

The system is configured for docker compose (V2 syntax shown; V1 compatibility retained via command substitution).

1. SSE Mode (Default Service): bash docker compose up -d mcp

2. API Mode (Ephemeral Run): bash docker compose run --rm mcp python splunk_mcp.py api

3. STDIO Mode (Interactive Stream): bash docker compose run -i --rm mcp python splunk_mcp.py stdio

Automated Testing via Docker

Dedicated environment for running test suites:

1. Execute the entire test suite: bash ./run_tests.sh --docker

2. Isolate service testing: bash

Start the core service container

docker compose up -d mcp

Start the isolated test runner container

docker compose up test

Run both until tests complete and containers exit

docker compose up --abort-on-container-exit

Test artifact collection is directed to the ./test-results directory.

Docker Workflow Tips

1. Image Building: bash

Build all required images

docker compose build

Build a specific component (e.g., the main service)

docker compose build mcp

1. Log Monitoring: bash

View combined output from all running services

docker compose logs

Tail logs for the primary MCP service in real-time

docker compose logs -f mcp

1. Debugging Access: bash

Run the service with verbose debugging enabled

DEBUG=true docker compose up mcp

Gain interactive shell access within the running service container

docker compose exec mcp /bin/bash

Note: Substitute docker compose with docker-compose if employing V1 syntax.

Security Guidelines

1. Configuration Secrecy:
2. Ensure sensitive .env files are excluded from version control.
3. Utilize .env.example as a template for required variables.

4. Employ Docker secrets management for production deployment credentials.

5. TLS Trust Configuration:

6. Setting VERIFY_SSL=true is mandated for production security.
7. Disabling verification (false) is only permissible for sandbox or self-signed testing.

8. Configuration is primarily managed via environment variables.

9. Network Exposure:

10. Limit exposed container ports strictly to what is necessary.
11. Prefer utilizing internal Docker overlay networks where possible.
12. Rigorous network policy enforcement is essential in live environments.

Environment Configuration Variables

Runtime behavior is governed by the following environment parameters: - SPLUNK_HOST: Network address or hostname of the Splunk deployment. - SPLUNK_PORT: The specific management port (default is 8089). - SPLUNK_USERNAME: Credentials for basic authentication. - SPLUNK_PASSWORD: Corresponding secret for basic authentication. - SPLUNK_TOKEN: (Exclusive) An API token, which overrides username/password if present. - SPLUNK_SCHEME: Connection protocol; defaults to secure HTTPS (https). - VERIFY_SSL: Boolean flag controlling X.509 certificate validation (default: true). - FASTMCP_LOG_LEVEL: Sets the verbosity of the logging output (e.g., DEBUG, INFO; default: INFO). - SERVER_MODE: Explicitly sets the operational mode when launched via Uvicorn (sse, api, stdio).

SSL Verification Options

The utility offers granular control over the TLS handshake process:

1. Secure Production Mode: env VERIFY_SSL=true

2. Executes complete certificate validation, including hostname matching.

3. The recommended standard for securing connections to trusted CAs.

4. Development/Bypass Mode: env VERIFY_SSL=false

5. Skips all certificate chain and hostname verification.

6. Intended only for scenarios involving development servers or self-signed certificates.

Quality Assurance

The project maintains high code quality via extensive testing frameworks (Pytest) and dedicated end-to-end validation using a mock MCP client framework.

Executing Tests

Execute standard test collection: bash poetry run pytest

To generate a code coverage report: bash poetry run pytest --cov=splunk_mcp