ceph-mcp

A read-only MCP server for Rook-Ceph clusters running on Kubernetes.

It lets an LLM (Claude, etc.) inspect the health of a Ceph cluster — cluster health, OSD tree, PG status, pool usage, mon quorum, RGW multisite sync — by executing a fixed set of ceph / radosgw-admin commands inside the Rook-Ceph toolbox pod and returning structured JSON.

Why it's safe to hand to an LLM

• No arbitrary commands. Every tool maps to exactly one hardcoded command template in commands.py. There is no code path that builds a shell command from model input — the model can only pick which tool to call, never what to run.

• Read-only. Only inspection commands (ceph health, ceph osd tree, ceph df, radosgw-admin sync status, ...) are exposed. Nothing that mutates cluster state.

• Scoped exec, not a shell. Commands run via the Kubernetes exec API inside the existing rook-ceph-tools pod — the server itself never needs cluster-admin credentials beyond what your kubeconfig already grants.

Related MCP server: MCP Notes Server

Tools

Every tool returns a JSON envelope:

{ "ok": true, "tool": "get_cluster_health", "data": { ... }, "warnings": [] }

or, on failure:

{ "ok": false, "tool": "get_cluster_health", "error": "...", "detail": "..." }

Requirements

• Python >= 3.14

• A Kubernetes cluster running Rook-Ceph, with the rook-ceph-tools toolbox pod deployed

• A working kubeconfig with permission to list/exec pods in the Rook-Ceph namespace

Installation

Once published to PyPI, run it with uvx — no separate install step needed:

uvx ceph-mcp

Or install it into a virtualenv:

uv pip install ceph-mcp

From source

git clone git@github.com:sserkanml/ceph-mcp.git
cd ceph-mcp
uv sync
uv run ceph-mcp

Configuration

Configured entirely through environment variables:

Usage with Claude Desktop

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%/Claude/claude_desktop_config.json

Published (PyPI) version:

{
  "mcpServers": {
    "ceph-mcp": {
      "command": "uvx",
      "args": ["ceph-mcp"],
      "env": {
        "CEPH_MCP_NAMESPACE": "rook-ceph",
        "CEPH_MCP_TOOLBOX_LABEL": "app=rook-ceph-tools"
      }
    }
  }
}

From a local checkout:

{
  "mcpServers": {
    "ceph-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/ceph-mcp", "ceph-mcp"],
      "env": {
        "CEPH_MCP_NAMESPACE": "rook-ceph",
        "CEPH_MCP_TOOLBOX_LABEL": "app=rook-ceph-tools"
      }
    }
  }
}

See examples/claude_desktop_config.json for a ready-to-copy version.

Development

Project layout:

src/ceph_mcp/
├── server.py       # MCP server entrypoint + tool registration
├── commands.py     # fixed allowlist: tool name -> ceph/radosgw-admin command
├── config.py       # env var -> Config resolution
├── k8s_exec.py     # finds the toolbox pod, execs commands via the k8s API
└── parsers/        # raw ceph JSON/text -> structured tool output
tests/
├── fixtures/       # captured real ceph/radosgw-admin output, used by parser tests
└── test_*.py

Run the test suite:

uv run pytest

Lint:

uv run ruff check .

Debugging

Since MCP servers communicate over stdio, use the MCP Inspector to interact with the server directly:

npx @modelcontextprotocol/inspector uv --directory /absolute/path/to/ceph-mcp run ceph-mcp

Publishing to PyPI

uv sync
uv build
uv publish

Requires PyPI credentials via UV_PUBLISH_TOKEN (or --token).

License

MIT — see LICENSE.

Author

Serkan (@sserkanml)