Fastmcp Runner
Generic bootstrap container for running FastMCP servers from private registries
Ask AI about Fastmcp Runner
Powered by Claude · Grounded in docs
I know everything about Fastmcp Runner. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
FastMCP Runner
A generic OCI-based runner for MCP (Model Context Protocol) servers. Pulls container images from registries and runs them without requiring a Docker daemon.
Overview
FastMCP Runner is a bootstrap container that pulls and executes MCP server images at runtime. It works with any MCP server packaged as a container image, not just FastMCP applications. This is useful for environments like Hugging Face Spaces where you cannot run arbitrary Docker images directly.
Documentation
Full documentation is available at fastmcp-runner.readthedocs.io
Quick Start
docker run \
-e IMAGE=ghcr.io/your-org/your-mcp-server:latest \
-e PORT=8000 \
-e REGISTRY_USER=username \
-e REGISTRY_PASSWORD=token \
-p 8000:8000 \
ghcr.io/drengskapur/fastmcp-runner:latest-stable
For public images, omit REGISTRY_USER and REGISTRY_PASSWORD.
Image Tags
| Tag | Description | Use Case |
|---|---|---|
latest | Built on every push to main | Development, staging |
latest-stable | Promoted via release workflow | Production |
vX.Y.Z | Specific version | Pinned deployments |
Environment Variables
| Variable | Required | Description |
|---|---|---|
IMAGE | Yes | Full OCI image reference to pull and run |
PORT | Yes | Port for the MCP server (1-65535) |
REGISTRY_USER | No | Username for private registry authentication |
REGISTRY_PASSWORD | No | Password/token for private registry authentication |
MCP_TRANSPORT | No | Transport type: streamable-http (default) or sse |
MCP_HOST | No | Bind address (default: 0.0.0.0) |
MCP_PATH | No | MCP endpoint path (default: /mcp) |
HEALTHCHECK_PATH | No | Health check path (default: /health) |
LOG_LEVEL | No | Logging level: debug, info, warn, error |
LOG_FORMAT | No | Log format: text or json |
MCP_ENV_* | No | Passthrough variables (prefix stripped before passing to app) |
How It Works
- Validates required environment variables
- Authenticates to registry (if credentials provided), then clears credentials
- Fetches image configuration to determine entrypoint and environment
- Extracts application directories (
/app,/data,/home,/opt, site-packages) - Drops privileges to non-root user (UID 1000)
- Executes the image's configured entrypoint/command
Security
- Credentials cleared immediately after authentication
- Application runs as non-root user (UID 1000)
- System directories excluded from extraction (only application paths copied)
- Base image: Chainguard wolfi-base
- All images signed with Sigstore cosign
Verify Image Signature
cosign verify ghcr.io/drengskapur/fastmcp-runner:latest-stable \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
--certificate-identity-regexp 'https://github.com/drengskapur/fastmcp-runner/.*'
Requirements
The target image must have:
- A valid entrypoint or command that starts an MCP server
- Application code in extractable paths (
/app,/opt,/home, or site-packages) - The server must bind to
0.0.0.0and read port fromPORTenvironment variable
License
Apache 2.0
