# 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](#get-the-full-boilerplate).

## 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:

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

## Quick start

```bash
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](https://srmcguirt.gumroad.com/l/fastmcp-python)**

## Related tools

- [MCP Server Starter Kit](https://srmcguirt.gumroad.com/l/mcp-starter) — TypeScript MCP server with Zod + Docker ($49)
- [MCP Vertical Server Bundle](https://srmcguirt.gumroad.com/l/mcp-vertical-bundle) — GitHub, Slack, Notion MCP servers ($99)
- [Multi-Agent Orchestration Kit](https://srmcguirt.gumroad.com/l/multi-agent-kit) — pipeline + fan-out patterns ($79)
- [Claude Agent Boilerplate](https://srmcguirt.gumroad.com/l/claude-agent) — tool-use loop core ($29)

Full lineup: [srmcguirt.dev](https://srmcguirt.dev)

## License

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