slurm-mcp

A Model Context Protocol (MCP) server that exposes read-only Slurm REST API endpoints as MCP tools. This server connects to your Slurm cluster via the official Slurm REST API, providing secure, read-only access to job and cluster information. You can use it with Cursor, any other MCP-compatible tool.

Quick start (npx)

SLURM_API_BASE_URL="http://YOUR-SLURM-REST:6820" \
SLURM_API_VERSION="v0.0.40" \
SLURM_AUTH_MODE="bearer" \
SLURM_API_KEY="YOUR_TOKEN" \
SLURM_USERNAME="root" \
NPM_CONFIG_YES=true npx slurm-mcp@latest

• ESM only; Node >= 20 required.
• The server starts and waits on stdio for an MCP client.

Integrate with Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "slurm": {
      "command": "npx",
      "args": ["-y", "slurm-mcp@latest"],
      "env": {
        "SLURM_API_BASE_URL": "http://YOUR-SLURM-REST:6820",
        "SLURM_API_VERSION": "v0.0.40",
        "SLURM_AUTH_MODE": "bearer",
        "SLURM_API_KEY": "YOUR_TOKEN",
        "SLURM_USERNAME": "root",
        "SLURM_TTL_NODES": "60",
        "SLURM_TTL_QUEUE": "10",
        "SLURM_TTL_PARTITIONS": "60",
        "SLURM_TTL_JOB": "5"
      }
    }
  }
}

Tools

• slurm_ping: Slurm REST health (core/db)
• slurm_cluster_info: API metadata and ping results
• slurm_queue_summary: Totals and per-partition pending/running
• slurm_job_get: Get job by ID (tries core, falls back to SlurmDB)
• slurm_jobs_search: Flexible job search (user/states/partitions/window)
• slurm_jobs_list: Cluster-wide list (no user filter)
• slurm_jobs_list_for_user: List jobs for a specific user
• slurm_jobs_history: Historical jobs over a time window
• slurm_partitions_list: Partitions and limits
• slurm_nodes_list: Node summaries
• slurm_node_get_by_name: Get a single node by name
• slurm_nodes_search_by_feature: Nodes filtered by feature
• slurm_fairshare_get: Fairshare info for a user

Examples

• Search nodes by feature:

{ "feature": "gpu" }

• Get node by name:

{ "name": "c002" }

Configuration (env)

Required:

• SLURM_API_BASE_URL: Base URL to slurmrestd (no trailing /slurm)
• SLURM_AUTH_MODE: bearer or header
• SLURM_API_KEY: token (Bearer or X-SLURM-USER-TOKEN)
• SLURM_USERNAME: only needed when header mode is used

Optional:

• SLURM_API_VERSION: default v0.0.40
• SLURM_CLUSTER_ID: default default
• SLURM_REQUEST_TIMEOUT_MS: default 5000
• SLURM_DEFAULT_HISTORY_DAYS: default 7
• SLURM_DEFAULT_MAX_RESULTS: default 100
• Cache TTLs: SLURM_TTL_QUEUE (10), SLURM_TTL_PARTITIONS (60), SLURM_TTL_NODES (60), SLURM_TTL_JOB (5)

Security & efficiency

• Read-only wrapper; no write operations to Slurm are exposed.
• Response caching with short TTLs to reduce load.
• Bounded queries (limits, cursors) to avoid expensive scans.