# mcp-server-template

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

A minimal, well-structured starter template for building [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers in Python using [FastMCP](https://github.com/jlowin/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

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

```bash
# 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()`:

```python
@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

```bash
# 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`

```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](https://spec.modelcontextprotocol.io/) — The full protocol spec
- [MCP Documentation](https://modelcontextprotocol.io/introduction) — Guides and tutorials
- [FastMCP](https://github.com/jlowin/fastmcp) — The Python framework this template uses
- [MCP Server Examples](https://github.com/modelcontextprotocol/servers) — Official reference servers

## License

MIT License. See [LICENSE](LICENSE) for details.