Python integrations: see the package namespace migration guide.
MCP Server for Splunk
Enable AI agents to interact seamlessly with Splunk environments through the Model Context Protocol (MCP)
Transform your Splunk instance into an AI-native platform. Our community-driven MCP server bridges Large Language Models and Splunk Enterprise/Cloud with 20+ tools, 16 resources (including CIM data models), and production-ready security—all through a single, standardized protocol.
🌟 Why This Matters
- 🔌 Universal AI Connection: One protocol connects any AI to Splunk data
- ⚡ Zero Custom Integration: No more months of custom API development
- 🛡️ Production-Ready Security: Client-scoped access with no credential exposure
- 🤖 AI-Powered Workflows: Intelligent troubleshooting agents that work like experts
- 🤝 Community-Driven: Extensible framework with contribution examples
🚀 NEW: AI-Powered Troubleshooting Workflows - Transform reactive firefighting into intelligent, systematic problem-solving with specialist AI workflows.
📋 Table of Contents
🚀 Quick Start
Prerequisites
- Python 3.11+ and UV package manager
- Nodejs (optional used for mcp inspector)
- Docker (optional but recommended for full stack)
- Splunk instance with API access (or use included Docker Splunk)
Python 3.10 is no longer supported: the patched DNS and file-lock dependencies
require Python 3.11 or newer. Upgrade Python before updating this server.
📖 Complete Setup Guide: Installation Guide
Configuration
Before running the setup, configure your Splunk connection:
# Copy the example configuration
cp env.example .env
# Edit .env with your Splunk credentials
# - Use your existing Splunk instance (local, cloud, or Splunk Cloud)
# - OR use the included Docker Splunk (requires Docker)
# Optional HTTP transport defaults (local runs)
# - Stateless HTTP avoids sticky-session requirements
# - JSON responses improve compatibility with some clients
# These are already the defaults for local runs via `mcp-server --local`
echo "MCP_STATELESS_HTTP=true" >> .env
echo "MCP_JSON_RESPONSE=true" >> .env
One-Command Setup
Windows:
git clone https://github.com/deslicer/mcp-for-splunk.git
cd mcp-for-splunk
```python
# Start the MCP Server (project script)
uv run mcp-server --local --detached
# Verify the server
uv run mcp-server --test
# Optional: show detailed tools/resources and health output
uv run mcp-server --test --detailed
macOS/Linux:
git clone https://github.com/deslicer/mcp-for-splunk.git
cd mcp-for-splunk
# (Recommended) Preview what would be installed
./scripts/smart-install.sh --dry-run
# Install missing prerequisites (base: Python, uv, Git, Node)
./scripts/smart-install.sh
# Start the MCP Server (project script)
# Local runs default to HTTP stateless mode + JSON response
uv run mcp-server --local --detached
# Verify the server
uv run mcp-server --test
# Optional: show detailed tools/resources and health output
uv run mcp-server --test --detailed
💡 Deployment Options: The mcp-server command will prompt you to choose:
- Docker (Option 1): Full stack with Splunk, Traefik, MCP Inspector - recommended if Docker is installed
- Local (Option 2): Lightweight FastMCP server only - for users without Docker
Stopping services:
uv run mcp-server --stop stops only this project's compose services (dev/prod/splunk). It does not stop the Docker engine.
Note on Splunk licensing: When using the so1 Splunk container, you must supply your own Splunk Enterprise license if required. The compose files include a commented example mount:
# - ./lic/splunk.lic:/tmp/license/splunk.lic:ro. Create a lic/ directory and mount your license file, or add the license via the Splunk Web UI after startup.
🎯 What You Can Do
🤖 Workflow Discovery & Authoring
Discover and validate Splunk troubleshooting workflow definitions (JSON) without a built-in agent runner:
# Discover available troubleshooting workflows
result = await list_workflows.execute(ctx, format_type="summary")
# Returns: missing_data_troubleshooting, performance_analysis, custom_workflows...
# Author or validate a workflow definition
result = await workflow_builder.execute(
ctx=ctx,
mode="validate",
workflow_data={"workflow_id": "my_check", "tasks": [...]},
)
OpenAI-based workflow_runner execution was removed in favor of FastMCP 4 / MCP SDK v2. Workflow JSON definitions remain available for discovery, validation, and external orchestration.
📖 Workflows Guide → for creation, templates, and contrib workflows.
🛡️ ITSI MCP Server (NEW!)
A dedicated Model Context Protocol server for Splunk IT Service Intelligence ships in this repo at mcp_itsi/, released independently to PyPI as mcp-itsi-server. It targets ITSI 4.21 and adds 70 tools, 9 documentation resources, and 3 workflow prompts for managing services, entities, KPIs, episodes, glass tables, deep dives, correlation searches, and aggregation policies.
# Standalone install
pip install mcp-itsi-server
# Together with the parent server
pip install "mcp-server-for-splunk[itsi]"
You can deploy it two ways with identical capabilities:
- Plugin of
mcp-for-splunk — auto-registers via the mcp_splunk.plugins Python entry point. One process, one URL, one credential set.
- Standalone — its own FastMCP HTTP/stdio process, behind Traefik on
/itsi/mcp (Docker), via mcp-itsi-server (local Python), or as the mcp_itsi Docker image (anywhere).
Both modes share the same per-request X-Splunk-* headers as the parent server (basic auth, bearer token, splunkd session token), plus optional X-ITSI-* overrides for app/user namespace.
🚀 ITSI Getting Started → | 🏗️ ITSI Deployment Guide → | 📦 Package README →
📚 Documentation Hub
🔧 Available Tools & Capabilities
🤖 Workflow Tools
list_workflows: Discover available troubleshooting workflows (core + contrib)workflow_builder: Create, edit, and validate workflow JSON definitionsworkflow_requirements: Schema and authoring guidance for workflow contributors- Built-in Workflows: Missing data troubleshooting, performance analysis, and more
- 📖 Complete Workflow Guide →
🔍 Search & Analytics
- Smart Search: Natural language to SPL conversion
- Real-time Search: Background job management with progress tracking
- Saved Searches: Create, execute, and manage search automation
📊 Data Discovery
- Metadata Exploration: Discover indexes, sources, and sourcetypes
- Schema Analysis: Understand your data structure
- Usage Patterns: Identify data volume and access patterns
👥 Administration
- App Management: List, enable, disable Splunk applications
- User Management: Comprehensive user and role administration
- Configuration Access: Read and analyze Splunk configurations
🏥 Health Monitoring
- System Health: Monitor Splunk infrastructure status
- Degraded Feature Detection: Proactive issue identification
- Alert Management: Track and analyze triggered alerts
🛡️ Splunk IT Service Intelligence (ITSI) — NEW!
The companion mcp_itsi server (standalone or plugin — see 🛡️ ITSI MCP Server) adds 70 ITSI-specific tools:
- Service Insights: services, service templates, KPI base searches, KPI threshold templates, glass tables, deep dives, home views — full CRUD plus
itsi_count_services and itsi_templatize_service.
- Entity Integration: entities, entity types, alias inventory; full CRUD with the documented schema quirks (alias fields must also live at the document root).
- Event Analytics: notable events with
itsi_acknowledge_notable_event / itsi_close_notable_event shortcuts, plus full CRUD on aggregation policies and correlation searches.
- Teams, maintenance windows, supported object types, and bundled docs as
itsi_* tools and itsi://docs/<slug> resources.
📦 Browse the ITSI tool catalog →
🌐 Client Integration Examples
💪 Multi-Client Configuration Strength: One of the key advantages of this MCP Server for Splunk is its ability to support multiple client configurations simultaneously. You can run a single server instance and connect multiple clients with different Splunk environments, credentials, and configurations - all without restarting the server or managing separate processes.
🔄 Multi-Client Benefits
Session-Based Isolation: Each client connection maintains its own Splunk session with independent authentication, preventing credential conflicts between different users or environments.
Dynamic Configuration: Switch between Splunk instances (on-premises, cloud, development, production) by simply changing headers - no server restart required.
Scalable Architecture: A single server can handle multiple concurrent clients, each with their own Splunk context, making it ideal for team environments, CI/CD pipelines, and multi-tenant deployments.
Resource Efficiency: Eliminates the need to run separate MCP server instances for each Splunk environment, reducing resource consumption and management overhead.
Cursor IDE
Single Tenant
{
"mcpServers": {
"splunk": {
"command": "fastmcp",
"args": ["run", "/path/to/src/mcp_server_for_splunk/server.py"],
"env": {
"MCP_SPLUNK_HOST": "your-splunk.com",
"MCP_SPLUNK_USERNAME": "your-user"
}
}
}
}
Client Specified Tenant
Sessionless bearer-token (default HTTP mode) and session-scoped examples:
{
"mcpServers": {
"splunk-sessionless": {
"url": "http://localhost:8003/mcp/",
"headers": {
"X-Splunk-Host": "myorg.splunkcloud.com",
"X-Splunk-Port": "8089",
"X-Splunk-Token": "eyJraWQiOiJzcGx1bmsuc2VjcmV0...",
"X-Splunk-Scheme": "https",
"X-Splunk-Verify-SSL": "true"
}
},
"splunk-in-docker": {
"url": "http://localhost:8003/mcp/",
"headers": {
"X-Splunk-Host": "so1",
"X-Splunk-Port": "8089",
"X-Splunk-Username": "admin",
"X-Splunk-Password": "Chang3d!",
"X-Splunk-Scheme": "http",
"X-Splunk-Verify-SSL": "false",
"X-Session-ID": "splunk-in-docker-session"
}
}
}
}
See HTTP Client Connection Modes for both approaches.
Google Agent Development Kit
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
splunk_agent = LlmAgent(
model='gemini-2.0-flash',
tools=[MCPToolset(connection_params=StdioServerParameters(
command='fastmcp',
args=['run', '/path/to/src/mcp_server_for_splunk/server.py']
))]
)
🤝 Community & Contribution
Quick links: Contributing · Code of Conduct · Security Policy · Governance · License
🛠️ Create Your Own Tools & Extensions
🚀 Quick Start for Contributors:
# Interactive tool generator (project script)
uv run generate-tool
# Browse existing tools for inspiration
./contrib/scripts/list_tools.py
# Validate your tool implementation (project script)
uv run validate-tools
# Test your contribution
./contrib/scripts/test_contrib.py
📖 Complete Contributing Guide → - Everything you need to know about creating tools, resources, and workflows for the MCP Server for Splunk.
Contribution Categories
- 🛡️ Security Tools: Threat hunting, incident response, security analysis
- ⚙️ DevOps Tools: Monitoring, alerting, operations, SRE workflows
- 📈 Analytics Tools: Business intelligence, reporting, data analysis
- 💡 Example Tools: Learning templates and patterns for new contributors
- 🔧 Custom Workflows: AI-powered troubleshooting procedures for your organization
🚀 Deployment Options
Development (Local)
- Startup Time: ~10 seconds
- Resource Usage: Minimal (single Python process)
- Best For: Development, testing, stdio-based AI clients
- HTTP Defaults: Local runs enable
MCP_STATELESS_HTTP=true and MCP_JSON_RESPONSE=true by default for Official MCP clients (no sticky sessions; JSON over SSE).
- Endpoint:
http://localhost:8003/mcp/
- Client headers:
Accept: application/json, text/event-stream plus X-Splunk-* (prefer X-Splunk-Token; or username/password)
- Sessionless (default): omit
X-Session-ID / MCP-Session-ID
- Session-scoped: send a stable
X-Session-ID when you want cached config across requests
- Details: HTTP Client Connection Modes
Production (Docker)
- Features: Load balancing, health checks, monitoring
- Includes: Traefik, MCP Inspector, optional Splunk
- Best For: Multi-client access, web-based AI agents
- Session Routing: Traefik is configured with sticky sessions for streamable HTTP; alternatively, enable stateless HTTP for development scenarios.
Enterprise (Kubernetes)
- Scalability: Horizontal scaling, high availability
- Security: Pod-level isolation, secret management
- Monitoring: Comprehensive observability stack
ITSI MCP Server
- Plugin mode: Auto-loads into
mcp-for-splunk via the mcp_splunk.plugins entry point — single process, single URL.
- Standalone mode: Dedicated FastMCP container behind Traefik at
/itsi/mcp, or mcp-itsi-server console script for local Python, or mcp_itsi Docker image for any orchestrator.
- Auth parity: Same
X-Splunk-* headers as the parent server; optional X-ITSI-App / X-ITSI-User-NS / X-ITSI-API-Version for ITSI-specific namespacing.
- Verification:
uv run python scripts/test_itsi_mcp_both_modes.py exercises both modes end-to-end against any live ITSI cluster.
📖 Full ITSI deployment guide →
🆘 Support & Community
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📖 Documentation: Complete guides and references
- 🔧 Interactive Testing: MCP Inspector for real-time testing
Windows Support
Windows users get first-class support with PowerShell scripts and comprehensive troubleshooting guides. See our Windows Setup Guide.
📈 Project Stats
- ✅ 20+ Production Tools - Comprehensive Splunk operations
- ✅ 16 Rich Resources - System info, documentation, and CIM data models
- ✅ Comprehensive Test Suite - 170+ tests passing locally
- ✅ Multi-Platform - Windows, macOS, Linux support
- ✅ Community-Ready - Structured contribution framework
- ✅ Enterprise-Proven - Production deployment patterns
🎯 Ready to Get Started?
Choose your adventure:
Learn More: Model Context Protocol | FastMCP Framework
