How do I use mcp-beaker?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-beaker reserve a system for Fedora 38" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-beaker

by faizbawa

Overview Schema Related Servers Score Discussions

Python

Remote

mcp-beaker

PyPI Version PyPI Downloads License Python

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

25 tools covering the full Beaker lifecycle: systems, jobs, distros, tasks
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).

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

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

"-e", "BEAKER_SSL_VERIFY=false",

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-----",

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

Variable	Required	Default	Description
`BEAKER_URL`	Yes	--	Base URL of your Beaker server
`BEAKER_AUTH_METHOD`	No	`kerberos`	`kerberos` or `password`
`BEAKER_KERBEROS_BACKEND`	No	`http`	`http` (native SPNEGO) or `bkr` (bkr CLI)
`BEAKER_USERNAME`	For password auth	--	Beaker username
`BEAKER_PASSWORD`	For password auth	--	Beaker password
`BEAKER_OWNER`	No	`$USER`	Default owner for job queries
`BEAKER_SSL_VERIFY`	No	`true`	Verify SSL certificates
`BEAKER_CA_CERT`	No	--	Path to CA certificate bundle
`KRB5_PRINCIPAL`	Container only	--	Kerberos principal for `kinit` inside container
`KRB5_PASSWORD`	Container only	--	Kerberos password for `kinit` inside container
`BEAKER_CA_CERT_DATA`	Container only	--	PEM-encoded CA certificate written to file at startup

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 (13)

Tool	Description
`list_systems`	List systems by availability (all/available/free)
`get_system_details`	Hardware specs, ownership, status for a system
`get_system_history`	Activity history for a system
`get_system_arches`	Supported OS families and architectures
`list_jobs`	Filter jobs by owner, status, whiteboard
`get_job_status`	Job status with failure diagnosis
`get_job_results_xml`	Export job results as XML
`get_job_logs`	List log files for a job/recipe/task
`list_distro_trees`	Search distros by name, family, arch, tags
`list_os_families`	List all known OS families
`whoami`	Show authenticated user info
`list_lab_controllers`	List all lab controllers
`search_tasks`	Search the task library

Write Tools (12)

Tool	Description
`submit_job`	Submit a job from XML (with validation and auto-fill)
`clone_job`	Clone and resubmit an existing job
`cancel_job`	Cancel a running/queued job
`watch_job`	Poll until completion with failure analysis and auto-retry
`reserve_system`	Manually reserve a system
`release_system`	Release a manually reserved system
`loan_system`	Grant a loan for a system to a user
`return_loan`	Return a current system loan
`power_system`	Power on/off/reboot a system
`provision_system`	Provision a reserved system with a distro
`extend_watchdog`	Extend a running task's watchdog timer
`set_job_response`	Ack/nak (waive) a recipe set result

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:

Value	Backend	Install
`http` (default)	Native GSSAPI/SPNEGO -- lightweight, pip-installable	`pip install mcp-beaker[kerberos]`
`bkr`	`bkr` CLI subprocesses -- traditional, requires RPM	`yum install beaker-client`

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 (4 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

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

6dRelease cycle

8Releases (12mo)

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/faizbawa/mcp-beaker'

If you have feedback or need assistance with the MCP directory API, please join our Discord server