mcp-beaker

MCP server for Beaker lab automation -- system provisioning, job management, distro discovery, and failure diagnosis.

Works with any Beaker server instance. Built on FastMCP v3 and designed for use with AI coding assistants (Cursor, Claude Desktop, etc.).

Features

• 27 tools covering the full Beaker lifecycle: systems, jobs, distros, tasks
• Hostname filter: list or search systems by FQDN substring (e.g. ampere-mtsnow), combined with availability presets (free/available/all)
• Beaker Py3 compatible: works with both legacy and modernized Beaker REST APIs
• Flexible auth: Kerberos (native GSSAPI/SPNEGO or bkr CLI fallback) and password (XML-RPC)
• Job XML validation: auto-fills missing fields, infers distro families
• Failure diagnosis: deep analysis with auto-retry on correctable failures
• 10 documentation topics exposed as MCP resources
• 2 workflow prompts for common tasks (reserve system, diagnose job)
• Generic: works with any Beaker URL, configurable SSL/CA settings

Installation

Container (recommended)

The container image bundles everything -- no host dependencies beyond podman (or docker). Kerberos authentication happens inside the container via KRB5_PRINCIPAL and KRB5_PASSWORD environment variables.

# Pull the pre-built image from GHCR
podman pull ghcr.io/faizbawa/mcp-beaker:latest

# Or build locally from the repo
podman build -t mcp-beaker:latest -f Containerfile .

Pip / uvx

# Using uv (recommended)
pip install uv
uvx mcp-beaker

# Using pip
pip install mcp-beaker
mcp-beaker

# With native Kerberos support (no bkr CLI needed -- requires krb5-devel on host)
pip install mcp-beaker[kerberos]

# Local development
uv run --directory /path/to/mcp-beaker mcp-beaker

Configuration

Cursor / VS Code

Add to your .cursor/mcp.json (or .vscode/mcp.json):

Container (recommended)

{
  "mcpServers": {
    "beaker": {
      "command": "podman",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-e", "BEAKER_URL=https://beaker.example.com",
        "-e", "KRB5_PRINCIPAL=your-user@YOUR.REALM",
        "-e", "KRB5_PASSWORD=your-kerberos-password",
        "ghcr.io/faizbawa/mcp-beaker:latest"
      ]
    }
  }
}

The container runs kinit internally -- no volume mounts, no host dependencies. Use --network=host so the container can reach your Kerberos KDC and Beaker server (especially over VPN).

Container with mounted ticket cache (no password in config)

Instead of storing your Kerberos password in mcp.json, you can mount a pre-existing ticket cache from the host:

Step 1 -- Create a file-based ticket on the host:

kinit -c FILE:/tmp/krb5cc_beaker your-user@YOUR.REALM

Re-run this whenever the ticket expires (typically every 10 hours).

Step 2 -- Mount the ticket into the container:

{
  "mcpServers": {
    "beaker": {
      "command": "podman",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-v", "/tmp/krb5cc_beaker:/tmp/krb5cc_0:ro,Z",
        "-e", "BEAKER_URL=https://beaker.example.com",
        "ghcr.io/faizbawa/mcp-beaker:latest"
      ]
    }
  }
}

The container detects the valid ticket and skips kinit entirely. No KRB5_PRINCIPAL or KRB5_PASSWORD needed. The :ro,Z mount flags ensure read-only access with proper SELinux labeling.

Note: The host typically uses KCM (D-Bus) for credential storage, which containers cannot access. That's why you need kinit -c FILE:... to create a file-based cache that can be bind-mounted.

SSL certificates: Many Beaker servers use internal CA certificates that are not in the container's default trust store. You have three options:

1. Disable verification (simplest, fine on a trusted corporate network):

"-e", "BEAKER_SSL_VERIFY=false",

2. Pass CA cert inline via BEAKER_CA_CERT_DATA (no volume mount needed):

"-e", "BEAKER_CA_CERT_DATA=-----BEGIN CERTIFICATE-----\nMIID...your-ca-cert...\n-----END CERTIFICATE-----",

3. Mount a CA bundle (single file):

"-v", "/path/to/ca-bundle.crt:/tmp/ca-bundle.crt:ro",
"-e", "BEAKER_CA_CERT=/tmp/ca-bundle.crt",

Pip / uvx

{
  "mcpServers": {
    "beaker": {
      "command": "uvx",
      "args": ["mcp-beaker[kerberos]"],
      "env": {
        "BEAKER_URL": "https://beaker.example.com",
        "BEAKER_AUTH_METHOD": "kerberos",
        "BEAKER_KERBEROS_BACKEND": "http"
      }
    }
  }
}

Streamable HTTP mode

uvx mcp-beaker --transport streamable-http --port 8000

{
  "mcpServers": {
    "beaker": {
      "url": "http://localhost:8000/mcp",
      "type": "streamableHttp"
    }
  }
}

Environment Variables

CLI Options

mcp-beaker [OPTIONS]

Options:
  --transport [stdio|sse|streamable-http]  Transport type (default: stdio)
  --port INTEGER                           Port for HTTP transports (default: 8000)
  --host TEXT                              Host for HTTP transports (default: 0.0.0.0)
  --path TEXT                              Path for streamable-http (default: /mcp)
  --beaker-url TEXT                        Beaker server URL
  --ssl-verify / --no-ssl-verify           Verify SSL certs (default: verify)
  --ca-cert TEXT                           CA certificate bundle path
  --auth-method [kerberos|password]        Authentication method
  --kerberos-backend [http|bkr]            Kerberos backend (default: http)
  --read-only                              Disable all write tools
  --enabled-tools TEXT                     Comma-separated tools to enable
  -v, --verbose                            Increase verbosity (-v info, -vv debug)
  --version                                Show version
  --help                                   Show this message

Tools

Read Tools (15)

Write Tools (12)

Authentication

Kerberos (recommended)

Ensure you have a valid ticket:

kinit your-username@YOUR.REALM

The server supports two Kerberos backends, controlled by BEAKER_KERBEROS_BACKEND:

Both backends use the same Kerberos ticket from kinit.

Password

Set BEAKER_AUTH_METHOD=password along with BEAKER_USERNAME and BEAKER_PASSWORD. The server authenticates via the XML-RPC auth.login_password() method. Note: this requires server-side LDAP to be enabled.

Architecture

src/mcp_beaker/
  __init__.py           # Click CLI entry point
  config.py             # BeakerConfig dataclass
  exceptions.py         # Custom exceptions
  client.py             # BeakerClient (XML-RPC + REST)
  models/               # Pydantic response models
  servers/
    __init__.py         # FastMCP server, lifespan, DI helper
    systems.py          # System tools (6 read + 6 write)
    jobs.py             # Job tools (4 read + 6 write)
    distros.py          # Distro tools (2 read)
    tasks.py            # Task tools (1 read)
    general.py          # General tools (2 read)
    prompts.py          # Workflow prompt templates
    resources.py        # Beaker documentation resources
  utils/
    xml_validation.py   # Job XML validation/auto-fill
    diagnosis.py        # Failure analysis engine
    formatting.py       # Human-readable formatters
    bkr_cli.py          # bkr CLI helpers
    parsing.py          # ID parsing utilities

Development

cd mcp-beaker
uv sync --dev
uv run pytest
uv run ruff check src/

License

MIT