splunk-cluster-mcp

splunk-cluster-mcp

A small MCP that makes Claude a bit easier to use against a distributed Splunk cluster. Point it at the cluster manager and it discovers the rest — indexer peers, search head cluster captain, license manager — then routes each tool to the right node.

Built because: Splunk's official MCP is single-instance. In a multi-node cluster, some things live on the cluster manager, some on a search head, some on the license manager. I wanted Claude to figure that out instead of me telling it for every call.

---

What this is — and isn't

A small quality-of-life layer for cluster setups. It:

• Doesn't add any new Splunk capability — everything here is already in Splunk's REST API
• Doesn't replace Splunk's official MCP — the two are complementary
• Doesn't ship enterprise auth — uses a single shared credential (basic auth with a least-privilege role, or a bearer token for single-instance / SHC)
• Does save you from juggling a dozen SSH sessions to read cluster-wide state
• Does keep working when your SHC captain changes (re-discovers on every refresh)
• Does fan out to all peers in parallel for cluster-wide queries (disks, indexes)

If you run a single Splunk instance, just use Splunk's official MCP — it has more depth (knowledge objects, AI helpers). This project earns its keep only when you have a distributed cluster.

---

Install — Claude Code Plugin Marketplace (recommended)

The fastest way. Inside any Claude Code session:

/plugin marketplace add ALPERKESKE/splunk-cluster-mcp
/plugin install splunk-cluster-mcp@splunk-cluster-mcp

Claude Code clones the repo into ~/.claude/plugins/cache and registers the MCP automatically. Restart Claude Code if it doesn't pick the plugin up on its own.

First-run: ask Claude to connect to your cluster.

Connect to my Splunk cluster — CM is https://cm.example.com:8089,
SHC bootstrap is https://sh1.example.com:8089, user mcp-readonly / <password>.

Claude calls cluster_connect(...) and the rest of the tools become live.

Install — manual (without Claude Code plugin system)

If you prefer to wire the MCP up yourself:

git clone https://github.com/ALPERKESKE/splunk-cluster-mcp.git
cd splunk-cluster-mcp
uv sync
claude mcp add splunk-cluster --scope user -- \
  uv --directory "$(pwd)" run python -m splunk_cluster_mcp.server

Or add to .mcp.json manually:

{
  "mcpServers": {
    "splunk-cluster": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/path/to/splunk-cluster-mcp", "run", "python", "-m", "splunk_cluster_mcp.server"]
    }
  }
}

---

Tool catalog

Tool	Routes to	Notes
cluster_connect	—	runtime credential setup (in-memory only)
cluster_connection_status	—	diagnostic — are we connected, where to
cluster_health	Cluster Manager	peers up/searchable, bundle, fixups
list_peers	Cluster Manager	indexer cluster peer detail
shc_status	SHC Captain (or any member)	members, captain, sync state
list_indexes	Cluster Manager	cluster-wide index list with bucket health
index_detail	Cluster Manager	deep info on a single index
node_disk	All nodes (fan-out)	partition usage per node, hottest partition
tail_log	Any node (SSH)	tail splunkd, license_usage, metrics, …
license_status	License Manager	stacks, pools, violations
list_users	Cluster Manager	users + roles (with capabilities if detailed=true)
search	SHC Captain (dynamic)	SPL via async job, cluster-wide

---

Credentials — three options

Auth modes: Two supported — pick based on topology.

• HTTP basic auth (recommended for a distributed cluster). Username + password for a shared least-privilege Splunk role. Works against every node in the cluster.
• Bearer token (recommended for single-instance or SHC-only). Create one in Splunk via Settings → Tokens → New Token (or POST /services/authorization/tokens). Tokens can be scoped per-role and revoked individually, but they are not portable across the indexer cluster or license manager — see the note below.

Use a least-privilege role for the user / token — not full admin. See SECURITY.md.