FastMCP Python Boilerplate

Production-ready FastMCP Python boilerplate for building MCP servers that work with Claude, GPT, Cursor, and any MCP-compatible agent.

What's included

• FastMCP server setup with proper tool schemas
• Pydantic v2 config validation — reads from .env, never hardcodes secrets
• Token-bucket rate limiter — thread-safe, per-client windows
• structlog to stderr — structured logging that doesn't break MCP protocol framing
• pytest suite, 36 tests — config, rate limiter, tools, and a subprocess-level check that stdout never carries anything but JSON-RPC

Docker packaging, CI, pre-commit, and the Claude Desktop config ship with the full package.

The stdout/stderr gotcha

MCP uses stdout for JSON-RPC frames. Any print() that lands on stdout corrupts the protocol — the client sees malformed JSON and either drops the message or errors out. All logging goes to stderr.

This boilerplate has it wired by default:

import structlog, sys
structlog.configure(logger_factory=structlog.PrintLoggerFactory(file=sys.stderr))

Quick start

git clone https://github.com/srmcguirt/fastmcp-python-boilerplate
cd fastmcp-python-boilerplate
cp .env.example .env
pip install -r requirements.txt
python server.py

Structure

fastmcp-python-boilerplate/
├── mcp_server/
│   ├── __main__.py        # Entrypoint: python -m mcp_server
│   ├── server.py          # FastMCP server + example tools
│   ├── config.py          # Pydantic v2 settings (reads from .env)
│   ├── logger.py          # structlog wired to stderr
│   └── rate_limiter.py    # Thread-safe token bucket
├── tests/
│   ├── test_config.py
│   ├── test_rate_limiter.py
│   ├── test_server.py
│   └── test_logging_stdout_purity.py   # proves stdout stays JSON-RPC only
├── .env.example
├── pyproject.toml
└── LICENSE

Everything above is MIT licensed and runs as-is. pytest passes 36 tests, including a suite that spawns a subprocess and asserts at the file-descriptor level that no log output ever reaches stdout.

Get the Full Boilerplate

The free core above is a working server with the patterns wired up.

The full $35 package adds the deployment layer:

• Multi-stage Dockerfile with health check, non-root user
• Docker Compose with env file support
• Three real tool implementations beyond the examples here
• Per-tool rate limits with configurable burst
• Request ID tracing through the structlog pipeline
• Integration tests against a mocked MCP client
• Pre-commit hooks (ruff, mypy)
• GitHub Actions CI workflow
• Claude Desktop + Claude Code config
• Deployment guide with troubleshooting

-> Get FastMCP Python Boilerplate — $35

Related tools

• MCP Server Starter Kit — TypeScript MCP server with Zod + Docker ($49)
• MCP Vertical Server Bundle — GitHub, Slack, Notion MCP servers ($99)
• Multi-Agent Orchestration Kit — pipeline + fan-out patterns ($79)
• Claude Agent Boilerplate — tool-use loop core ($29)

Full lineup: srmcguirt.dev

License

MIT — use it in production, keep it if you never buy anything.