Splunk MCP Server
An MCP (Model Context Protocol) server for retrieving data from Splunk Enterprise or Splunk Cloud.
Features
- FastMCP Framework: Simplified server implementation
- Splunk Integration: Direct REST API integration (no SDK dependency)
- Multiple Transports: Supports both stdio and SSE
- Docker Support: Ready for containerized deployment
- SPL Query Validation: Built-in guardrails to detect risky, inefficient, or destructive queries
- Output Sanitization: Automatic masking of sensitive data (credit cards, SSNs)
- Multiple Output Formats: JSON, Markdown, CSV, and Summary formats
- Essential Tools:
validate_spl: Validate SPL queries for risks and inefficienciessearch_oneshot: Run blocking search queriessearch_export: Stream search results immediatelyget_indexes: List available Splunk indexesget_saved_searches: List saved searchesrun_saved_search: Execute saved searchesget_config: Get server configuration
Quick Start
1. Setup Environment
cd /path/to/splunk-mcp-server/python
cp .env.example .env
# Edit .env with your Splunk connection details
2. Install Dependencies
pip install -e .
3. Run the Server
SSE Mode (default):
python server.py
Stdio Mode: Configure via environment or let the client spawn the server.
4. Test with Example Clients
cd tests
# For SSE transport
python test_sse_transport.py
# For stdio transport
python test_stdio_transport.py
# Test SPL validation interactively
python validate_spl_test.py
# Interactive SPL search
python splunk_sse_search.py
# Or use the comprehensive test menu
./testall
Docker Deployment
# Using the dock script for common operations:
# Build and start containers
./dock rebuild
# Start containers
./dock up # or ./dock start
# Stop containers
./dock down # or ./dock stop
# Restart containers
./dock restart
# Manual docker commands:
sudo docker compose build --no-cache
sudo docker compose up -d
Client Configuration
Claude Desktop
SSE Mode Configuration:
Edit your Claude Desktop configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/claude/claude_desktop_config.json
{
"mcpServers": {
"splunk-mcp": {
"url": "http://localhost:8050/sse"
}
}
}
Stdio Mode Configuration:
{
"mcpServers": {
"splunk-mcp": {
"command": "python",
"args": ["/path/to/splunk-mcp-server/python/server.py"],
"env": {
"TRANSPORT": "stdio",
"SPLUNK_HOST": "your-splunk-host",
"SPLUNK_USERNAME": "your-username",
"SPLUNK_PASSWORD": "your-password"
}
}
}
}
Claude Code
SSE Mode Configuration:
Start the server:
cd /path/to/splunk-mcp-server/python
python server.py
Add to Claude Code:
claude mcp add --transport sse --scope project splunk-mcp-server http://localhost:8050/sse
Stdio Mode Configuration:
cd /path/to/splunk-mcp-server/python
claude mcp add splunk-mcp-server -e TRANSPORT=stdio --scope project -e SPLUNK_HOST=your-host -e SPLUNK_USERNAME=your-user -e SPLUNK_PASSWORD=your-pass -- python server.py
# claude mcp remove splunk-mcp-server [--scope project]
Available Tools
validate_spl
Validate an SPL query for potential risks and inefficiencies before execution.
Parameters:
query: The SPL query to validate
Returns:
risk_score: Risk score from 0-100risk_message: Detailed explanation of risks found with suggestionsrisk_tolerance: Current risk tolerance settingwould_execute: Whether this query would execute or be blockedexecution_note: Clear message about execution status
Example:
validate_spl("index=* | delete")
search_oneshot
Run a blocking search query and return results.
Parameters:
query: Splunk search query (e.g., "index=main | head 10")earliest_time: Start time (default: "-24h")latest_time: End time (default: "now")max_count: Maximum results (default: 100 or SPL_MAX_EVENTS_COUNT)output_format: Format for results - json, markdown/md, csv, or summary (default: "json")risk_tolerance: Override risk tolerance level (default: SPL_RISK_TOLERANCE)sanitize_output: Override output sanitization (default: SPL_SANITIZE_OUTPUT)
Example:
search_oneshot("index=_internal | head 5", earliest_time="-1h", output_format="markdown")
search_export
Stream search results immediately without creating a job.
Parameters:
query: Splunk search queryearliest_time: Start time (default: "-24h")latest_time: End time (default: "now")max_count: Maximum results (default: 100 or SPL_MAX_EVENTS_COUNT)output_format: Format for results - json, markdown/md, csv, or summary (default: "json")risk_tolerance: Override risk tolerance level (default: SPL_RISK_TOLERANCE)sanitize_output: Override output sanitization (default: SPL_SANITIZE_OUTPUT)
get_indexes
List all available Splunk indexes with properties.
get_saved_searches
List all saved searches with their queries and descriptions.
run_saved_search
Execute a saved search by name.
Parameters:
search_name: Name of the saved searchtrigger_actions: Whether to trigger actions (default: False)
get_config
Get current server configuration (excludes sensitive data).
Configuration
Edit .env file to customize:
# Server Configuration
SERVER_NAME=Splunk MCP
SERVER_DESCRIPTION=MCP server for retrieving data from Splunk
HOST=0.0.0.0
PORT=8050
TRANSPORT=sse
LOG_LEVEL=INFO
# Splunk Configuration
SPLUNK_HOST=localhost
SPLUNK_PORT=8089
SPLUNK_USERNAME=admin
SPLUNK_PASSWORD=changeme
# Optional: Use token instead of username/password
SPLUNK_TOKEN=
# SSL verification
VERIFY_SSL=false
# Search Configuration
# Maximum number of events to return from searches (0 = unlimited)
SPL_MAX_EVENTS_COUNT=100000
# Risk tolerance level for SPL query validation (0 = reject all risky queries, 100 = allow all)
SPL_RISK_TOLERANCE=75
# Safe time range for searches - queries within this range get no time penalty
SPL_SAFE_TIMERANGE=24h
# Enable output sanitization to mask sensitive data (credit cards, SSNs)
SPL_SANITIZE_OUTPUT=false
Common Splunk Search Patterns
Get recent errors:
index=main level=ERROR | head 20
Get statistics by source:
index=_internal | stats count by source
Time-based searches:
index=main earliest=-1h latest=now | timechart count
Field extraction:
index=web_logs | rex field=_raw "status=(?<status_code>\d+)" | stats count by status_code
SPL Query Validation (Guardrails)
The server includes built-in validation to detect potentially risky or inefficient SPL queries before execution. This helps prevent:
- Destructive Operations: Commands like
deletethat permanently remove data - Performance Issues: Unbounded searches, expensive commands, or missing time ranges
- Resource Consumption: Queries that could overwhelm system resources
- Security Risks: External script execution or unsafe operations
Risk Scoring
Each query is analyzed and assigned a risk score from 0-100:
- 0-30: Low risk - Query is generally safe
- 31-60: Medium risk - Query may have performance implications
- 61-100: High risk - Query could be destructive or severely impact performance
Common Risk Factors
-
Destructive Commands (High Risk):
deletecommand (+80 points)collectwithoverride=true(+25 points)outputlookupwithoverride=true(+20 points)
-
Time Range Issues:
- All-time searches or missing time constraints (+50 points)
- Time ranges exceeding safe threshold (+20 points)
-
Performance Concerns:
index=*without constraints (+35 points)- Expensive commands like
transaction,map,join(+20 points each) - Missing index specification (+20 points)
- Subsearches without limits (+20 points)
-
Security Risks:
- External script execution (+40 points)
Configuration
Configure validation behavior in your .env file:
SPL_RISK_TOLERANCE: Set threshold for blocking queries (default: 75)SPL_SAFE_TIMERANGE: Define safe time range (default: 24h)SPL_SANITIZE_OUTPUT: Enable/disable output sanitization
Output Sanitization
When SPL_SANITIZE_OUTPUT=true, the server automatically masks sensitive data:
- Credit Cards: Shows only last 4 digits (e.g., --****-1234)
- Social Security Numbers: Completely masked (e.g., --***)
Testing Validation
Use the interactive validation tool to test queries:
cd tests
python validate_spl_test.py
Security Notes
- Store credentials securely in
.envfile - Use token authentication when possible
- Enable SSL verification in production (
VERIFY_SSL=true) - Never commit
.envfile to version control
Troubleshooting
Connection Issues
- Verify Splunk is running and accessible
- Check firewall rules for port 8089
- Ensure credentials are correct
- Try disabling SSL verification for testing
Search Issues
- Verify user has search permissions
- Check index access rights
- Use
| headto limit results during testing - Check Splunk search job limits
Project Structure
python/
├── .env.example # Environment configuration template
├── server.py # Main server implementation
├── splunk_client.py # Splunk REST API client
├── helpers.py # Formatting utilities
├── guardrails.py # SPL query validation and sanitization
├── spl_risk_rules.py # Configurable risk rules for validation
├── pyproject.toml # Python project configuration
├── Dockerfile # Docker deployment configuration
├── docker-compose.yml # Docker compose configuration
├── dock # Docker management script
├── README.md # This file
└── tests/
├── test_sse_transport.py # SSE transport tests
├── test_stdio_transport.py # Stdio transport tests
├── validate_spl_test.py # Interactive validation tool
├── splunk_sse_search.py # Interactive search tool
├── testall # Comprehensive test menu
└── quick_test.py # Quick smoke test
Metadata
Release files for iflow-mcp_splunk_splunk-mcp-server 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_splunk_splunk_mcp_server-0.1.1.tar.gz | 22.2 kB | Without provenance | Details for iflow_mcp_splunk_splunk_mcp_server-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_splunk_splunk_mcp_server-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_splunk_splunk_mcp_server-0.1.1-py3-none-any.whl |
Total release size: 40.6 kB
Release files / iflow_mcp_splunk_splunk_mcp_server-0.1.1.tar.gz
| Download URL | iflow_mcp_splunk_splunk_mcp_server-0.1.1.tar.gz |
|---|---|
| Size | 22.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d36468a8dda07fd05dc07feabd5b7c4517fe2b8822000e119c51b491eee93152
|
|
BLAKE2b-256 checksum How to use checksums |
d0673e4e2b94cc2a3c0afb6b33b7e2460914940eb6a1049ac6ad58c9e8abbd73
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.28 {"installer":{"name":"uv","version":"0.9.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_splunk_splunk_mcp_server-0.1.1-py3-none-any.whl
| Download URL | iflow_mcp_splunk_splunk_mcp_server-0.1.1-py3-none-any.whl |
|---|---|
| Size | 18.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f0980e10043c5a689e22e395217bbd1c501b6a61710f8d194de21346534c50be
|
|
BLAKE2b-256 checksum How to use checksums |
2597194351eb931dc02eff5d85494e0e09e021b46a2896088aa9a99b5f8c1a69
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.28 {"installer":{"name":"uv","version":"0.9.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_splunk_splunk-mcp-server 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.