mcp-server-template

A minimal, production-ready boilerplate for building Python MCP servers. Build your first MCP server in 30 minutes.

Model Context Protocol (MCP) is how Claude connects to external tools. An MCP server describes "tools" that Claude can call — like checking a calendar, querying a database, or creating an invoice.

Think of it like a USB port for AI. You plug in a server, Claude gains a new ability.

mcp-server-template/
├── src/
│   └── my_mcp_server/
│       ├── __init__.py        # Package init
│       ├── __main__.py        # Entry point
│       └── server.py          # MCP server with example tools
├── tests/
│   └── test_server.py         # Example tests
├── pyproject.toml              # Package config (ready for PyPI)
├── README.md                   # This file
└── LICENSE                     # MIT

git clone https://github.com/NyxToolsDev/mcp-server-template.git my-mcp-server
cd my-mcp-server

python -m venv venv
venv\Scripts\activate  # Windows
# source venv/bin/activate  # Mac/Linux
pip install -e ".[dev]"

python -m my_mcp_server

Add to your Claude Code MCP config (~/.claude/mcp_servers.json):

{
  "my-mcp-server": {
    "command": "python",
    "args": ["-m", "my_mcp_server"],
    "env": {}
  }
}

Restart Claude Code. Your tools are now available.

Open src/my_mcp_server/server.py. You'll see an example tool:

@server.tool()
async def hello(name: str) -> str:
    """Say hello to someone."""
    return f"Hello, {name}!"

To add a new tool:

1. Write a function with type hints and a docstring
2. Decorate it with @server.tool()
3. Claude will automatically discover it

The docstring is critical — it tells Claude when and how to use the tool. Be specific.