# Splunk MCP Server

A Model Context Protocol (MCP) server that provides LLM-powered tools for interacting with Splunk Enterprise and Splunk Cloud. Built with [FastMCP](https://github.com/jlowin/fastmcp) (Python), it exposes 25 tools across four capability areas for search, alerting, KV Store management, and index administration.

Designed for use with **Claude Desktop** (via stdio transport) and **Llama Stack on OpenShift AI** (via streamable HTTP transport).

## Features

### Search & Investigation (7 tools)
- `splunk_search` — Run SPL queries synchronously (create job → poll → return results)
- `splunk_search_async` — Submit long-running searches, get job ID immediately
- `splunk_get_job_status` — Check search job progress and state
- `splunk_get_job_results` — Retrieve results from completed jobs
- `splunk_list_jobs` — List active and recent search jobs
- `splunk_cancel_job` — Cancel a running search job
- `splunk_export_search` — Stream large result sets via the export endpoint

### Saved Searches & Alerts (6 tools)
- `splunk_list_saved_searches` — List all saved searches and alerts
- `splunk_get_saved_search` — Get details of a specific saved search
- `splunk_create_saved_search` — Create new saved searches or alerts
- `splunk_update_saved_search` — Modify existing saved searches
- `splunk_delete_saved_search` — Remove a saved search
- `splunk_run_saved_search` — Dispatch a saved search immediately

### KV Store (7 tools)
- `splunk_list_kvstore_collections` — List all KV Store collections
- `splunk_get_kvstore_schema` — Get collection schema and field definitions
- `splunk_query_kvstore` — Query records with MongoDB-style filters
- `splunk_insert_kvstore_record` — Insert a new record
- `splunk_update_kvstore_record` — Update an existing record by key
- `splunk_delete_kvstore_record` — Delete a single record by key
- `splunk_delete_kvstore_records` — Bulk delete records matching a query

### Index & Data Management (5 tools)
- `splunk_list_indexes` — List all indexes with event counts and sizes
- `splunk_get_index` — Get detailed index configuration
- `splunk_list_sourcetypes` — List all sourcetypes with descriptions
- `splunk_list_inputs` — List configured data inputs
- `splunk_health_check` — Check Splunk instance health, KV Store, and connectivity

## Quick Start

### Prerequisites
- Python 3.10+
- A Splunk Enterprise or Cloud instance with REST API access (port 8089)

### Installation

```bash
git clone https://github.com/anatsheh84/splunk-mcp-server.git
cd splunk-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

### Configuration

Copy the example environment file and set your Splunk credentials:

```bash
cp .env.example .env
```

Edit `.env` with your Splunk connection details:

```env
SPLUNK_HOST=https://your-splunk-host
SPLUNK_PORT=8089
SPLUNK_USERNAME=admin
SPLUNK_PASSWORD=your-password
SPLUNK_VERIFY_SSL=false
SPLUNK_AUTH_TYPE=basic
SPLUNK_API_MODE=direct
```

**Configuration options:**
- `SPLUNK_AUTH_TYPE`: `basic` (username/password) or `token` (Splunk auth token)
- `SPLUNK_API_MODE`: `direct` (splunkd port 8089) or `web_proxy` (Splunk Web REST proxy via `/en-US/splunkd/__raw/`)
- `SPLUNK_VERIFY_SSL`: Set to `true` in production with valid certificates

### Test Connection

```bash
python3 test_connection.py
```

### Run the MCP Server

**stdio mode** (for Claude Desktop):
```bash
splunk-mcp
# or
MCP_TRANSPORT=stdio python3 -m splunk_mcp.server
```

**Streamable HTTP mode** (for Llama Stack / OpenShift AI):
```bash
MCP_TRANSPORT=streamable_http MCP_HTTP_PORT=8080 splunk-mcp
```

## Claude Desktop Integration

Add the following to your Claude Desktop MCP configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "splunk": {
      "command": "/path/to/splunk-mcp-server/.venv/bin/python",
      "args": ["-m", "splunk_mcp.server"],
      "env": {
        "SPLUNK_HOST": "https://your-splunk-host",
        "SPLUNK_PORT": "8089",
        "SPLUNK_USERNAME": "admin",
        "SPLUNK_PASSWORD": "your-password",
        "SPLUNK_VERIFY_SSL": "false",
        "SPLUNK_API_MODE": "direct",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}
```

Or use the included setup script:
```bash
./setup_claude_desktop.sh
```

## Docker

```bash
docker build -t splunk-mcp-server .
docker run -e SPLUNK_HOST=https://splunk:8089 \
           -e SPLUNK_USERNAME=admin \
           -e SPLUNK_PASSWORD=changeme \
           -e MCP_TRANSPORT=streamable_http \
           -p 8080:8080 \
           splunk-mcp-server
```

## Project Structure

```
splunk-mcp-server/
├── src/splunk_mcp/
│   ├── __init__.py
│   ├── server.py          # FastMCP server, lifespan, transport selection
│   ├── config.py           # Pydantic Settings (env vars)
│   ├── client.py           # Async HTTP client for Splunk REST API
│   ├── errors.py           # Splunk-specific error handling
│   ├── formatters.py       # Markdown/JSON response formatting
│   ├── tools/
│   │   ├── search.py       # 7 search tools
│   │   ├── saved_searches.py  # 6 saved search tools
│   │   ├── kvstore.py      # 7 KV Store tools
│   │   └── indexes.py      # 5 index/health tools
│   └── models/
│       ├── search.py       # Pydantic input models for search
│       ├── saved_searches.py
│       ├── kvstore.py
│       └── indexes.py
├── pyproject.toml
├── Dockerfile
├── .env.example
├── test_connection.py      # Quick connectivity test
├── test_tools_e2e.py       # End-to-end tool tests
└── claude_desktop_config.json  # Example Claude Desktop config
```

## License

MIT