A feature-complete Model Context Protocol (MCP) server template in Python using FastMCP. This starter demonstrates all major MCP features with clean, Pythonic code.

• Model Context Protocol
• Python SDK
• FastMCP Guide

• Python 3.11+
• uv (recommended) or pip

# Clone the repository
git clone https://github.com/SamMorrowDrums/mcp-python-starter.git
cd mcp-python-starter

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .

stdio transport (for local development):

uv run mcp-python-starter --stdio

HTTP transport (for remote/web deployment):

uv run mcp-python-starter --http --port 3000

This project includes VS Code configuration for seamless development:

1. Open the project in VS Code
2. The MCP configuration is in .vscode/mcp.json
3. Test the server using VS Code's MCP tools

1. Install the Dev Containers extension
2. Open command palette: "Dev Containers: Reopen in Container"
3. Everything is pre-configured and ready to use!

.
├── mcp_starter/
│   ├── __init__.py
│   ├── tools.py       # Tool definitions (hello, get_weather, ask_llm, etc.)
│   ├── resources.py   # Resource and template definitions
│   ├── prompts.py     # Prompt definitions
│   └── server.py      # Server orchestration (imports and wires modules)
├── .vscode/
│   ├── mcp.json       # MCP server configuration
│   ├── settings.json  # Python settings
│   └── extensions.json
├── .devcontainer/
│   └── devcontainer.json
├── pyproject.toml     # Project configuration (uv/pip, Ruff config)
└── .python-version

# Run the server (Python reloads automatically on changes)
uv run mcp-python-starter --stdio

# Use MCP Inspector for debugging
uv run mcp dev mcp_starter/server.py

# Format code
uv run ruff format .

# Lint
uv run ruff check .

# Lint with auto-fix
uv run ruff check --fix .

# Type check
uv run pyright

Python scripts reload automatically when run with uv run. For enhanced debugging, use mcp dev which provides the MCP Inspector UI.

The MCP Inspector is an essential development tool for testing and debugging MCP servers.

npx @modelcontextprotocol/inspector -- uv run mcp-python-starter

• Tools Tab: List and invoke all registered tools with parameters
• Resources Tab: Browse and read resources and templates
• Prompts Tab: View and test prompt templates
• Logs Tab: See JSON-RPC messages between client and server
• Schema Validation: Verify tool input/output schemas

1. Start Inspector before connecting your IDE/client
2. Use the "Logs" tab to see exact request/response payloads
3. Test tool annotations (ToolAnnotations) are exposed correctly
4. Verify progress notifications appear for long_task
5. Check that Context injection works for sampling tools

@mcp.tool(
    title="Say Hello",
    description="A friendly greeting tool",
    annotations={"readOnlyHint": True},
)
def hello(name: str) -> str:
    """Say hello to someone.
    
    Args:
        name: The name to greet
    """
    return f"Hello, {name}!"

@mcp.resource("greeting://{name}")
def greeting_template(name: str) -> str:
    """Generate a personalized greeting."""
    return f"Hello, {name}!"

@mcp.tool(title="Long Task")
async def long_task(
    task_name: str,
    ctx: Context[ServerSession, None],
) -> str:
    for i in range(5):
        await ctx.report_progress(
            progress=i / 5,
            total=1.0,
            message=f"Step {i + 1}/5",
        )
        await asyncio.sleep(1.0)
    return "Done!"

@mcp.tool(title="Ask LLM")
async def ask_llm(
    prompt: str,
    ctx: Context[ServerSession, None],
) -> str:
    result = await ctx.session.create_message(
        messages=[{"role": "user", "content": {"type": "text", "text": prompt}}],
        max_tokens=100,
    )
    return result.content.text

Copy .env.example to .env and configure:

cp .env.example .env

Contributions welcome! Please ensure your changes maintain feature parity with other language starters.

MIT License - see LICENSE for details.