Fastmcp Template
A minimal template for publishing a Fast MCP project.
Ask AI about Fastmcp Template
Powered by Claude Β· Grounded in docs
I know everything about Fastmcp Template. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
FastMCP Cookiecutter Template
π Production-ready FastMCP server template with mcp-refcache integration for building AI agent tools that handle large data efficiently.
Quick Start
Using Cookiecutter
# Install cookiecutter (one-time)
uv tool install cookiecutter
# or: pipx install cookiecutter
# Generate your project (interactive)
cookiecutter gh:l4b4r4b4b4/fastmcp-template
# Or use a variant directly with auto-detected GitHub info
cookiecutter gh:l4b4r4b4b4/fastmcp-template --no-input \
project_name="My Server" \
template_variant=standard \
github_username="$(gh api user --jq .login)" \
author_name="$(gh api user --jq .name)" \
author_email="$(gh api user --jq .email)"
# Navigate to your new project
cd your-mcp-server
# Start developing!
uv run pytest
uv run your-mcp-server stdio
π‘ Tip: If you have gh CLI authenticated, the template will auto-detect your GitHub username when creating repositories. For other fields, use the command above to pass your GitHub profile info automatically.
What You Get
A fully-configured FastMCP server with:
- β Reference-Based Caching - Handle large data without context window limits
- β Preview Generation - Automatic previews for large results
- β Pagination - Navigate datasets efficiently
- β Access Control - Separate user/agent permissions
- β Private Computation - Agents compute with values they cannot see
- β Docker Ready - Production containers with multi-stage builds
- β GitHub Actions - CI/CD with PyPI publishing and GHCR containers
- β Optional Langfuse - Built-in observability integration
- β Type-Safe - Full type hints with Pydantic models
- β Testing Ready - pytest with 73% coverage requirement
- β Pre-commit Hooks - Ruff formatting and linting
Template Variants
Choose a variant based on your needs:
| Variant | Demo Tools | Secret Tools | Langfuse | Custom Rules | Tests | Best For |
|---|---|---|---|---|---|---|
minimal | β | β | β | β | 60 | Production servers, clean slate |
standard | β | β | β | β | 75 | Recommended with observability |
full | β | β | β | β | 101 | Learning, reference implementation |
custom | (choose) | (choose) | (choose) | (choose) | varies | Advanced users, specific needs |
Minimal (Production)
Clean slate with no demo code - perfect for production servers:
cookiecutter gh:l4b4r4b4b4/fastmcp-template --no-input \
project_name="My Server" \
template_variant=minimal
Generates:
- β Health check tool
- β Cache query tool
- β Admin tools (permission-gated)
- β No demo/example code
- β No Langfuse dependency
Standard (Recommended)
Production-ready with Langfuse observability:
cookiecutter gh:l4b4r4b4b4/fastmcp-template --no-input \
project_name="My Server" \
template_variant=standard
Includes everything in minimal plus:
- β Langfuse tracing integration
- β Context management tools
- β Trace info tools
Full (Learning)
All features and examples for learning:
cookiecutter gh:l4b4r4b4b4/fastmcp-template --no-input \
project_name="My Server" \
template_variant=full
Includes everything plus:
- β
hello- Basic tool pattern - β
generate_items- Cached large data with RefCache - β
store_secret/compute_with_secret- Private computation pattern
Custom (Advanced)
Choose exactly which features you want:
cookiecutter gh:l4b4r4b4b4/fastmcp-template
# When prompted:
template_variant: custom
include_demo_tools [no]: yes
include_secret_tools [no]: no
include_langfuse [yes]: yes
include_custom_rules [no]: no
Or non-interactively:
cookiecutter gh:l4b4r4b4b4/fastmcp-template --no-input \
project_name="My Server" \
template_variant=custom \
include_demo_tools=yes \
include_secret_tools=no \
include_langfuse=yes \
include_custom_rules=no
This gives you full control over all 8 possible combinations of features.
Auto-Detecting Your GitHub Info
If you have gh CLI installed and authenticated, you can automatically use your GitHub profile information:
# Auto-detect GitHub username, name, and email
cookiecutter gh:l4b4r4b4b4/fastmcp-template \
github_username="$(gh api user --jq .login)" \
author_name="$(gh api user --jq .name)" \
author_email="$(gh api user --jq .email)"
Or create a shell alias for convenience:
# Add to ~/.bashrc or ~/.zshrc
alias mcp-new='cookiecutter gh:l4b4r4b4b4/fastmcp-template \
github_username="$(gh api user --jq .login)" \
author_name="$(gh api user --jq .name)" \
author_email="$(gh api user --jq .email)"'
# Then just run:
mcp-new
GitHub Repository Creation
The template can automatically create a GitHub repository and push your initial commit:
cookiecutter gh:l4b4r4b4b4/fastmcp-template
# When prompted:
create_github_repo [no]: yes
github_repo_visibility [public]: public # or private
Requirements:
- GitHub CLI installed (
brew install ghor see https://cli.github.com) - Authenticated with
gh auth login
What it does:
- Auto-detects your authenticated GitHub username
- Creates a new GitHub repository under your account
- Sets it as the remote origin
- Pushes the initial commit
If setup fails: The template will show warnings but won't abort. You can create the repo manually:
gh auth login # If not authenticated
gh repo create your-project --public --source=. --push
Note: Repository creation is enabled by default (create_github_repo=yes). Set to no if you want to skip it.
Initial Release & PyPI Publishing
The template can automatically trigger a v0.0.0 release that publishes to PyPI:
Step 1: Set up PyPI Pending Trusted Publisher (before generating)
- Go to https://pypi.org/manage/account/publishing/
- Add a "pending publisher" with:
- PyPI Project Name:
your-project-slug(e.g.,legal-mcp) - Owner: Your GitHub username (e.g.,
l4b4r4b4b4) - Repository: Same as project slug (e.g.,
legal-mcp) - Workflow name:
publish.yml - Environment:
pypi(or leave blank)
- PyPI Project Name:
Step 2: Generate with initial release enabled
cookiecutter gh:l4b4r4b4b4/fastmcp-template --no-input \
project_name="Legal MCP" \
template_variant=minimal \
github_username="$(gh api user --jq .login)" \
author_name="$(gh api user --jq .name)" \
author_email="$(gh api user --jq .email)" \
trigger_initial_release=yes
What happens:
- Project is generated
- GitHub repository is created (public)
- Branch protection ruleset is configured
v0.0.0tag is created and pushed- Release workflow triggers β publishes to PyPI automatically
Requirements:
- Public repository (PyPI trusted publishers require public repos)
- Pending trusted publisher configured on PyPI
ghCLI authenticated
Branch Protection
The template automatically sets up a branch protection ruleset for main with:
- β Pull request required - No direct pushes to main
- β
Required status checks - Must pass before merge:
- Lint & Format
- Test (Python 3.12)
- Test (Python 3.13)
- Security Scan
- CI Success
- β No force pushes - Protects commit history
This provides a solid foundation for DevOps workflows. You can extend it later with:
- Additional branches (develop, staging, production)
- Required reviewers
- Code owner reviews
- Deployment environments
View/edit rulesets: https://github.com/<username>/<repo>/settings/rules
If you skip the initial release, you can trigger it manually later:
git tag -a v0.0.0 -m "Initial release - validates release pipeline"
git push origin v0.0.0
Features
Reference-Based Caching (RefCache)
Instead of returning large data directly, return a reference:
@mcp.tool
@cache.cached(namespace="public")
async def fetch_large_dataset(query: str) -> list[dict]:
"""Fetch dataset - returns reference for large results."""
data = await get_data(query) # e.g., 10,000 rows
return data # RefCache automatically creates reference
Agent receives a reference instead of 10,000 rows in context window.
Private Computation
Store sensitive values agents can compute with but not read:
@mcp.tool
def store_secret(name: str, value: float) -> dict:
"""Store value with EXECUTE-only permission."""
policy = AccessPolicy(
user_permissions=Permission.FULL,
agent_permissions=Permission.EXECUTE, # Can use, cannot read
)
ref = cache.set(f"secret_{name}", value, policy=policy)
return {"ref_id": ref.ref_id}
@mcp.tool
def compute_with_secret(secret_ref: str, multiplier: float) -> dict:
"""Compute using secret without revealing it."""
secret = cache.resolve(secret_ref, actor=DefaultActor.system())
return {"result": secret * multiplier}
Project Structure
your-mcp-server/
βββ app/ # Application code
β βββ server.py # Main MCP server
β βββ tools/ # Tool modules
β βββ __main__.py # CLI entry point
βββ tests/ # Test suite
β βββ conftest.py
β βββ test_server.py
βββ docker/ # Docker configurations
β βββ Dockerfile.base # Python base with dependencies
β βββ Dockerfile # Production image
β βββ Dockerfile.dev # Development with hot reload
βββ .github/workflows/ # CI/CD pipelines
β βββ ci.yml # Lint, test, security
β βββ publish.yml # PyPI publishing
β βββ release.yml # Docker builds
βββ .agent/ # AI assistant workspace
β βββ scratchpad.md # Main session notes
β βββ goals/ # Goal tracking
β βββ scratchpad.md # Goals index
β βββ 00-Template-Goal/ # Goal template
β βββ 01-Initial-Setup-And-Release/ # First goal (validate 0.0.0 release)
βββ pyproject.toml # Project configuration
βββ docker-compose.yml # Local development
βββ README.md # Project documentation
Next Steps After Generation
-
Follow Goal 01 - Every generated project includes a first goal:
cd your-mcp-server cat .agent/goals/01-Initial-Setup-And-Release/scratchpad.mdThis guides you through:
- Setting up the development environment
- Running tests and quality checks
- Publishing version 0.0.0 to validate the release pipeline
-
Verify GitHub repository (if you enabled repo creation)
git remote -v # Check remote is set # Visit https://github.com/your-username/your-project -
Run the validation checklist
uv sync # Install dependencies uv run pytest # Run tests ruff check . --fix && ruff format . # Code quality -
Try the server
uv run your-mcp-server stdio -
Customize the .rules file (if you enabled custom rules)
- Edit the "Project-Specific Rules" section
- Add your team's conventions, constraints, or guidelines
-
Add your tools
- Create tool modules in
app/tools/ - Register in
app/server.py - Add tests in
tests/
- Create tool modules in
-
Configure GitHub publishing (optional)
- PyPI: Add trusted publisher at pypi.org
- GHCR: GitHub Actions will publish on release
Testing the Template
Automated CI Testing
The template is automatically tested on every push and pull request. CI validates 5 configurations:
- β Minimal - 60 tests
- β Standard - 75 tests
- β Full - 101 tests
- β Custom (demos only) - 85 tests
- β Custom (secrets only) - 76 tests
Each configuration is tested for:
- Successful project generation
- All tests passing
- Linting passes (ruff check)
- No hardcoded template values
- Correct test count
Local Testing
Test a specific variant before submitting changes:
# Test preset variants
./scripts/validate-template.sh minimal
./scripts/validate-template.sh standard
./scripts/validate-template.sh full
# Test custom combinations
./scripts/validate-template.sh custom-demos-only
./scripts/validate-template.sh custom-secrets-only
# Test all variants
./scripts/validate-template.sh --all
Manual Verification
Generate and test a project manually:
# Generate project
uv run cookiecutter . --output-dir /tmp/test-project --no-input \
project_name="Test Project" \
template_variant=full
# Test generated project
cd /tmp/test-project/test-project
uv run pytest -v
uv run ruff check .
Verification Report
See VERIFICATION.md for comprehensive manual testing results:
- Detailed test breakdowns for all variants
- Manual verification of demo tools functionality
- Architecture notes and troubleshooting guides
- 397 total tests verified across 5 configurations (60 + 75 + 101 + 85 + 76)
Features in Detail
Development
To work on the template itself (not generate projects):
git clone https://github.com/l4b4r4b4b4/fastmcp-template
cd fastmcp-template
# The actual template is in {{cookiecutter.project_slug}}/
ls "{{cookiecutter.project_slug}}/"
# Test template generation locally
cookiecutter . --no-input
# or
cookiecutter . # With prompts
Documentation
- Template README: See
{{cookiecutter.project_slug}}/README.mdfor generated project documentation - FastMCP: https://github.com/jlowin/fastmcp
- mcp-refcache: https://github.com/l4b4r4b4b4/mcp-refcache
- MCP Protocol: https://modelcontextprotocol.io/
Contributing
See CONTRIBUTING.md for development guidelines.
License
MIT License - see LICENSE for details.
Related Projects
- mcp-refcache - Reference-based caching for MCP servers
- FastMCP - High-performance MCP framework
- Model Context Protocol - Protocol specification
Generated with β€οΈ using Cookiecutter
