MCP Scaffold

MCP Server Scaffolding

Scaffold production-ready Python MCP servers with FastMCP.

Quick Start

Generate a new MCP server:

python scripts/scaffold.py my-server --output ./my-server

This creates a complete project structure with:

• server.py - Main server with example tool, resource, and prompt
• requirements.txt - Dependencies (fastmcp, pydantic)
• README.md - Usage instructions

Scaffolding Options

Minimal Server (Tools Only)

python scripts/scaffold.py my-server --template basic

Full Server (All Primitives)

python scripts/scaffold.py my-server --template full

With Specific Features

python scripts/scaffold.py my-server \
  --tools \
  --resources \
  --prompts \
  --lifespan \
  --output ./servers/my-server

Validation

Validate an existing MCP server:

python scripts/validate.py path/to/server.py

Checks:

• FastMCP import and initialization
• Tool definitions with proper type hints
• Resource URI patterns
• Pydantic Field usage
• Async function patterns

Project Structure

Generated projects follow this structure:

my-server/
├── server.py           # Main MCP server
├── requirements.txt    # Python dependencies
├── README.md          # Usage documentation
└── data/              # Default data directory (gitignored)

Templates

Basic Template

Minimal server with one tool:

from fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool
def hello(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run()

Full Template

Complete server with tools, resources, prompts, and lifespan. See assets/templates/full-server.py.

Reference Documentation

• FastMCP API: See references/FASTMCP-GUIDE.md for decorator syntax, type hints, and patterns
• Common Patterns: See references/PATTERNS.md for database connections, API clients, error handling
• Deployment: See references/DEPLOYMENT.md for stdio, HTTP, and Docker deployment

MCP Primitives Cheatsheet

Tools (Actions)

from pydantic import Field

@mcp.tool
def my_tool(
    param: str = Field(description="Parameter description"),
    optional: int = Field(default=10, description="Optional with default")
) -> dict:
    """Tool description shown to LLM."""
    return {"result": param}

Resources (Data)

@mcp.resource("myscheme://path/to/resource")
def static_resource() -> str:
    """Resource description."""
    return json.dumps({"data": "value"})

@mcp.resource("myscheme://items/{item_id}")
def dynamic_resource(item_id: str) -> str:
    """Dynamic resource with URI template."""
    return json.dumps({"id": item_id})

Prompts (Templates)

@mcp.prompt(name="my_prompt", tags={"category"})
def my_prompt(
    topic: str = Field(description="What to analyze")
) -> str:
    """Prompt description."""
    return f"Please analyze {topic} and provide insights."

Workflow

1. Scaffold - Generate project structure
2. Customize - Add your tools, resources, prompts
3. Validate - Check for common issues
4. Test - Run locally with python server.py
5. Deploy - Add to Claude Code with claude mcp add