mcp-server-template

A minimal, well-structured starter template for building Model Context Protocol (MCP) servers in Python using FastMCP.

What is MCP?

The Model Context Protocol is an open standard that lets AI assistants (Claude, GPT, etc.) call external tools and access data sources through a unified interface. An MCP server exposes tools that AI models can discover and invoke — think of it as building an API specifically designed for LLM consumption.

What this template provides

• A working MCP server with example tools you can run immediately
• Clean project structure using modern Python packaging (pyproject.toml)
• Type hints, docstrings, and error handling patterns to follow
• Test setup showing how to verify your tools work
• Linting config with Ruff

Clone it, delete the example tools, add your own, and you have a production-ready MCP server.

Quick start

# Clone the template
git clone https://github.com/futhgar/mcp-server-template.git
cd mcp-server-template

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

# Run the server
python -m src.server

The server starts in stdio mode by default, which is how MCP clients (like Claude Desktop) communicate with it. To test it interactively:

# If you have the MCP inspector installed
mcp dev src/server.py

Project structure

mcp-server-template/
├── src/
│   ├── __init__.py
│   └── server.py          # MCP server definition and tools
├── tests/
│   └── test_server.py     # Tool tests
├── pyproject.toml          # Project config, dependencies
├── LICENSE
├── .gitignore
└── README.md

Adding your own tools

Open src/server.py and add a new function decorated with @mcp.tool():

@mcp.tool()
def my_tool(query: str, limit: int = 10) -> str:
    """Short description of what this tool does.

    The docstring becomes the tool's description that the AI model sees,
    so write it clearly — explain what the tool does, what the parameters
    mean, and what it returns.

    Args:
        query: What to search for.
        limit: Maximum number of results to return.
    """
    # Your logic here
    results = do_something(query, limit)
    return format_results(results)

Key points:

• The function name becomes the tool name the model calls.
• The docstring becomes the tool description the model reads to decide when to use it.
• Type hints on parameters are required — they define the tool's input schema.
• Return a string (or something that serializes to string). The model reads the return value.
• Raise exceptions for errors — FastMCP handles them and reports them to the client.

Delete the example tools (system_info, find_files, word_frequency) once you understand the pattern.

How to test

# Run tests
pytest

# Run tests with output
pytest -v

# Lint
ruff check src/ tests/

The test file shows how to call your tool functions directly. Since MCP tools are regular Python functions under the hood, you can test them without spinning up a server.

Connecting to Claude Desktop

Add your server to Claude Desktop's config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/mcp-server-template"
    }
  }
}

Restart Claude Desktop and your tools will appear in the tool picker.

Resources

• MCP Specification — The full protocol spec
• MCP Documentation — Guides and tutorials
• FastMCP — The Python framework this template uses
• MCP Server Examples — Official reference servers

License

MIT License. See LICENSE for details.