lutz500/mcp-server

🛠 MCP Server Template

🚀 Features

This repository is a starter template for building a FastMCP server with Python.
It uses:

• FastMCP – MCP protocol server
• Pydantic / Pydantic Settings – type-safe configuration via environment variables
• uv – modern Python package manager and runtime
• Optional Docker support – for containerized deployment

The template helps you quickly start a production-ready MCP server with environment-based configuration, optional dev tools, and Docker deployment.

⚡Quick Start

Local Development

# 1. Create venv
uv venv

# 2. Activate venv
## Windows
.\.venv\Scripts\activate
## macOS/Linux
source .venv/bin/activate

# 3. Install dependencies  (prod + dev)
uv sync

# 4. Run server
uv run main.py

🐳 Docker Deployment

Build image

docker build -t mcp-server .

Run container

docker run --env-file .env -p 8000:8000 mcp-server

Or with Docker Compose:

docker-compose up

⚙️ Configuration

The server get configured using environment variables.
Create a .env file in the root directory or set them in the docker-compose.yaml

# ---- [Optional]: Server Settings ----
# Those values are also set as default values!
SERVER_NAME=MCP-Server
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
TRANSPORT=http

# ---- [Optional]: ENV-Vars ----
API_URL=https://test-api.com/v1/users

Behavior:

• Environment variables take highest precedence
• .env file is used as fallback
• Class defaults are used if neither is set

There are logs shown if certain variables are not set!

💻 Usage

Idea: Tools, Resources and promts are outsourced into the /src/tools folder. Here tools are clustered thematically.

Add tool

1. Create a new file if need:

touch /src/tools/<tool-file>.py

2. Add logic:

Add tool logic to <tool-file>.py

from utils.logger import logger
from core.server import mcp

@mcp.tool
def add(x: int, y: int) -> int:
    """Add two numbers."""
    logger.info(f"Adding {x} and {y}")
    return x + y

3. Register tool

To register tool add it as import to main.py

...
# Import tools to register them with the MCP instance
import tools.math  # noqa F401
import tools.<tool.py> # <- add here to register


def main():
    mcp.run(
        transport=settings.TRANSPORT,
        host=settings.SERVER_HOST,
        port=settings.SERVER_PORT,
        show_banner=False,
    )

...