Allows for interacting with Splunk Enterprise/Cloud through natural language queries. Supports executing Splunk searches, managing indexes, viewing users, and performing KV store operations.
Splunk MCP (Model Context Protocol) Tool
A FastMCP-based tool for interacting with Splunk Enterprise/Cloud through natural language. This tool provides a set of capabilities for searching Splunk data, managing KV stores, and accessing Splunk resources through an intuitive interface.
Operating Modes
The tool operates in three modes:
SSE Mode (Default)
Server-Sent Events based communication
Real-time bidirectional interaction
Suitable for web-based MCP clients
Default mode when no arguments provided
Access via
/sse
endpoint
API Mode
RESTful API endpoints
Access via
/api/v1
endpoint prefixStart with
python splunk_mcp.py api
STDIO Mode
Standard input/output based communication
Compatible with Claude Desktop and other MCP clients
Ideal for direct integration with AI assistants
Start with
python splunk_mcp.py stdio
Features
Splunk Search: Execute Splunk searches with natural language queries
Index Management: List and inspect Splunk indexes
User Management: View and manage Splunk users
KV Store Operations: Create, list, and manage KV store collections
Async Support: Built with async/await patterns for better performance
Detailed Logging: Comprehensive logging with emoji indicators for better visibility
SSL Configuration: Flexible SSL verification options for different security requirements
Enhanced Debugging: Detailed connection and error logging for troubleshooting
Comprehensive Testing: Unit tests covering all major functionality
Error Handling: Robust error handling with appropriate status codes
SSE Compliance: Fully compliant with MCP SSE specification
Available MCP Tools
The following tools are available via the MCP interface:
Tools Management
list_tools
Lists all available MCP tools with their descriptions and parameters
Health Check
health_check
Returns a list of available Splunk apps to verify connectivity
ping
Simple ping endpoint to verify MCP server is alive
User Management
current_user
Returns information about the currently authenticated user
list_users
Returns a list of all users and their roles
Index Management
list_indexes
Returns a list of all accessible Splunk indexes
get_index_info
Returns detailed information about a specific index
Parameters: index_name (string)
indexes_and_sourcetypes
Returns a comprehensive list of indexes and their sourcetypes
Search
search_splunk
Executes a Splunk search query
Parameters:
search_query (string): Splunk search string
earliest_time (string, optional): Start time for search window
latest_time (string, optional): End time for search window
max_results (integer, optional): Maximum number of results to return
list_saved_searches
Returns a list of saved searches in the Splunk instance
KV Store
list_kvstore_collections
Lists all KV store collections
create_kvstore_collection
Creates a new KV store collection
Parameters: collection_name (string)
delete_kvstore_collection
Deletes an existing KV store collection
Parameters: collection_name (string)
SSE Endpoints
When running in SSE mode, the following endpoints are available:
/sse: Returns SSE connection information in text/event-stream format
Provides metadata about the SSE connection
Includes URL for the messages endpoint
Provides protocol and capability information
/sse/messages: The main SSE stream endpoint
Streams system events like heartbeats
Maintains persistent connection
Sends properly formatted SSE events
/sse/health: Health check endpoint for SSE mode
Returns status and version information in SSE format
Error Handling
The MCP implementation includes consistent error handling:
Invalid search commands or malformed requests
Insufficient permissions
Resource not found
Invalid input validation
Unexpected server errors
Connection issues with Splunk server
All error responses include a detailed message explaining the error.
Prerequisites
Python 3.10 or higher
Poetry for dependency management
Splunk Enterprise/Cloud instance
Appropriate Splunk credentials with necessary permissions
Installation
Option 1: Local Installation
Clone the repository:
Install dependencies using Poetry:
Copy the example environment file and configure your settings:
Update the
.env
file with your Splunk credentials:
Option 2: Docker Installation
Pull the latest image:
Create your
.env
file as above or use environment variables directly.Run using Docker Compose:
Or using Docker directly:
Usage
Local Usage
The tool can run in three modes:
SSE mode (default for MCP clients):
STDIO mode:
Docker Usage
The project supports both the new docker compose
(V2) and legacy docker-compose
(V1) commands. The examples below use V2 syntax, but both are supported.
SSE Mode (Default):
API Mode:
STDIO Mode:
Testing with Docker
The project includes a dedicated test environment in Docker:
Run all tests:
Run specific test components:
Test results will be available in the ./test-results
directory.
Docker Development Tips
Building Images:
Viewing Logs:
Debugging:
Note: If you're using Docker Compose V1, replace docker compose
with docker-compose
in the above commands.
Security Notes
Environment Variables:
Never commit
.env
filesUse
.env.example
as a templateConsider using Docker secrets for production
SSL Verification:
VERIFY_SSL=true
recommended for productionCan be disabled for development/testing
Configure through environment variables
Port Exposure:
Only expose necessary ports
Use internal Docker network when possible
Consider network security in production
Environment Variables
Configure the following environment variables:
SPLUNK_HOST
: Your Splunk host addressSPLUNK_PORT
: Splunk management port (default: 8089)SPLUNK_USERNAME
: Your Splunk usernameSPLUNK_PASSWORD
: Your Splunk passwordSPLUNK_SCHEME
: Connection scheme (default: https)VERIFY_SSL
: Enable/disable SSL verification (default: true)FASTMCP_LOG_LEVEL
: Logging level (default: INFO)SERVER_MODE
: Server mode (sse, api, stdio) when using uvicorn
SSL Configuration
The tool provides flexible SSL verification options:
Default (Secure) Mode:
Full SSL certificate verification
Hostname verification enabled
Recommended for production environments
Relaxed Mode:
SSL certificate verification disabled
Hostname verification disabled
Useful for testing or self-signed certificates
Testing
The project includes comprehensive test coverage using pytest and end-to-end testing with a custom MCP client:
Running Tests
Basic test execution:
With coverage reporting:
With verbose output:
End-to-End SSE Testing
The project includes a custom MCP client test script that connects to the live SSE endpoint and tests all tools:
This script acts as an MCP client by:
Connecting to the
/sse
endpoint to get the messages URLSending tool invocations to the messages endpoint
Processing the SSE events to extract tool results
Validating the results against expected formats
This provides real-world testing of the SSE interface as it would be used by an actual MCP client.
Test Structure
The project uses three complementary testing approaches:
MCP Integration Tests (
tests/test_api.py
):Tests the MCP tools interface through
mcp.call_tool()
Verifies proper tool registration with FastMCP
Ensures correct response format and data structure
Validates error handling at the MCP interface level
Note: This file should ideally be renamed to
test_mcp.py
to better reflect its purpose
Direct Function Tests (
tests/test_endpoints_pytest.py
):Tests Splunk functions directly (bypassing the MCP layer)
Provides more comprehensive coverage of function implementation details
Tests edge cases, parameter variations, and error handling
Includes tests for SSL configuration, connection parameters, and timeouts
Uses parameterized testing for efficient test coverage
End-to-End MCP Client Tests (
test_endpoints.py
):Behaves like a real MCP client connecting to the SSE endpoint
Tests the complete flow from connection to tool invocation to response parsing
Validates the actual SSE protocol implementation
Tests tools with real parameters against the live server
Configuration Tests (
tests/test_config.py
):Tests for environment variable parsing
SSL verification settings
Connection parameter validation
Testing Tools
The tests support:
Async testing with pytest-asyncio
Coverage reporting with pytest-cov
Mocking with pytest-mock
Parameterized testing
Connection timeout testing
Troubleshooting
Connection Issues
Basic Connectivity:
The tool now performs a basic TCP connectivity test
Check if port 8089 is accessible
Verify network routing and firewalls
SSL Issues:
If seeing SSL errors, try setting
VERIFY_SSL=false
Check certificate validity and trust chain
Verify hostname matches certificate
Authentication Issues:
Verify Splunk credentials
Check user permissions
Ensure account is not locked
Debugging:
Set
FASTMCP_LOG_LEVEL=DEBUG
for detailed logsCheck connection logs for specific error messages
Review SSL configuration messages
SSE Connection Issues:
Verify SSE endpoint is accessible via
/sse
Check for proper content-type headers
Use browser developer tools to inspect SSE connections
Claude Integration
Claude Desktop Configuration
You can integrate Splunk MCP with Claude Desktop by configuring it to use either SSE or STDIO mode. Add the following configuration to your claude_desktop_config.json
:
STDIO Mode (Recommended for Desktop)
SSE Mode
Usage with Claude
Once configured, you can use natural language to interact with Splunk through Claude. Examples:
List available indexes:
Search Splunk data:
Get system health:
Manage KV stores:
The MCP tools will be automatically available to Claude, allowing it to execute these operations through natural language commands.
License
[Your License Here]
Acknowledgments
FastMCP framework
Splunk SDK for Python
Python-decouple for configuration management
SSE Starlette for SSE implementation
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
A FastMCP-based tool for interacting with Splunk Enterprise/Cloud through natural language. This tool provides a set of capabilities for searching Splunk data, managing KV stores, and accessing Splunk resources
- Operating Modes
- Features
- Available MCP Tools
- SSE Endpoints
- Error Handling
- Prerequisites
- Installation
- Usage
- Environment Variables
- Testing
- Claude Integration
- License
- Acknowledgments
Related Resources
Related MCP Servers
- -securityAlicense-qualityFastMCP is a comprehensive MCP server allowing secure and standardized data and functionality exposure to LLM applications, offering resources, tools, and prompt management for efficient LLM interactions.Last updated -3MIT License
- -securityAlicense-qualityAn MCP server that allows using natural language to manage Cloudflare resources (Workers, KV, R2, D1) through Claude Desktop, VSCode, and other MCP clients.Last updated -79Apache 2.0
- AsecurityFlicenseAqualityA FastMCP tool that enables control of Spotify through natural language commands in Cursor Composer, allowing users to manage playback, search for content, and interact with playlists.Last updated -5
- -securityFlicense-qualityAn MCP server that enables LLMs to access Slack's search functionality to retrieve users, channels, messages, and thread replies from a Slack workspace.Last updated -3