fastmcp-server-template

This is a template repository. Click "Use this template" to create your own MCP server, then follow TEMPLATE.md to customise it.

A production-ready FastMCP server scaffold with batteries included:

• Auth — bearer token, OIDC, and multi-auth (both simultaneously)

• Read-only mode — write tools hidden via mcp.disable(tags={"write"})

• CI — test matrix (Python 3.11–3.14), ruff, mypy, pip-audit, gitleaks, CodeQL

• Release pipeline — semantic-release → PyPI + Docker (GHCR), SBOM attestation

• Docker — multi-arch, gosu privilege dropping, configurable PUID/PGID

• Docs — MkDocs Material + GitHub Pages

Quick start

# Install and run (stdio transport)
pip install fastmcp-server-template[mcp]
mcp-server serve

# Or with HTTP transport
mcp-server serve --transport http --port 8000

Configuration

All configuration is via environment variables prefixed with MCP_SERVER_:

Authentication

The server supports four auth modes:

1. Multi-auth — both bearer token and OIDC configured; either credential accepted

2. Bearer token — set MCP_SERVER_BEARER_TOKEN to a secret string

3. OIDC — full OAuth 2.1 flow via OIDC_CONFIG_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, and BASE_URL

4. No auth — server accepts all connections (default)

Auth requires --transport http (or sse). It has no effect with --transport stdio.

See Authentication guide for full setup details.

Docker

docker compose up -d

See Docker deployment for volumes, UID/GID, and Traefik setup.

Development

uv sync
uv run pytest
uv run ruff check src/ tests/
uv run mypy src/

Using this template

See TEMPLATE.md for the step-by-step customisation guide, including the rename.sh bootstrap script.

Keeping derived repos in sync

See SYNC.md for the infrastructure vs domain boundary definition and the cherry-pick workflow for propagating non-domain changes between this template and derived repositories.

License

MIT