python-mcp-server-template by nnamon - MCP Server

Python MCP Server Template

A minimal template for creating MCP (Model Context Protocol) servers in Python using the FastMCP framework.

Overview

This template provides a clean, simple starting point for building MCP servers. It demonstrates the three core MCP primitives with minimal examples that you can easily customize for your specific use case.

Features

Tools: 2 example tools using @mcp.tool() decorators
Resources: 2 example resources with @mcp.resource() decorators
Prompts: 2 example prompts using @mcp.prompt() decorators
Type Safety: Pydantic models for validation
Testing: Basic test suite covering all functionality
Docker Support: Ready-to-use containerization
Development Tools: Modern tooling with uv, ruff, and pytest

Quick Start

Prerequisites

Python 3.12+
uv (recommended)

Installation

Clone this template:

git clone PLACEHOLDER_REPO_URL PLACEHOLDER_PROJECT_NAME
cd PLACEHOLDER_PROJECT_NAME

Install dependencies:
```
make install
```
Run the server:
```
make run
```
Test the installation:
```
make test
```

Project Structure

src/mcp_server_template/
├── __init__.py              # Package initialization
├── server.py                # Main MCP server with tools, resources, and prompts
└── models.py                # Example Pydantic data models
tests/
└── test_server.py           # Basic test suite
main.py                      # Entry point for the server
pyproject.toml              # Project configuration and dependencies
Makefile                    # Development commands
Dockerfile                  # Container configuration
docker-compose.yml          # Docker orchestration

What's Included

Tools

add_numbers(a: int, b: int) -> int: Add two numbers together
echo_message(message: str) -> str: Echo back a message

Resources

config://app: Get application configuration
greeting://{name}: Get a personalized greeting for any name

Prompts

review_code(code: str): Generate a code review prompt
explain_concept(concept: str): Generate an explanation prompt

Data Models

ExampleModel: A basic Pydantic model with id, name, description, and timestamp

Customization Guide

Quick Start Options

Option 1: Automated Script (Recommended)

Run the initialization script for guided setup:

./initialize.sh

This script will:

Guide you through project setup questions
Replace all placeholders with your values
Rename packages and update imports
Run tests to verify everything works
Clean up template-specific files
Generate project-specific documentation

Option 2: Claude Code Slash Command

If you're using Claude Code, use the built-in slash command:

/project:new-project

This command will automatically:

Detect if this is a spawned project
Guide you through project setup questions
Replace all placeholders with your values
Rename packages and update imports
Verify everything builds correctly

Option 3: Manual Customization

If you prefer to customize manually, follow these steps to adapt the template for your specific use case:

1. Update Project Metadata

Edit pyproject.toml:

[project]
name = "placeholder-mcp-server-name"
description = "PLACEHOLDER_SERVER_DESCRIPTION"

Also update the hatch build configuration:

[tool.hatch.build.targets.wheel]
packages = ["src/placeholder_package_name"]  # Change from mcp_server_template

2. Rename the Package

Replace mcp_server_template throughout the codebase:

# Rename the package directory
mv src/mcp_server_template src/placeholder_package_name

# Update import in main.py
# Change: from src.mcp_server_template.server import mcp
# To:     from src.placeholder_package_name.server import mcp

# Update import in tests/test_server.py
# Change: from src.mcp_server_template.server import (...)
# To:     from src.placeholder_package_name.server import (...)

3. Replace the Example Tools

Edit src/placeholder_package_name/server.py:

@mcp.tool()
def your_custom_tool(param: str) -> dict:
    """Your tool description"""
    # Replace with your logic
    return {"result": f"Processed: {param}"}

4. Replace the Example Resources

@mcp.resource("your-scheme://path")
def your_resource() -> str:
    """Your resource description"""
    # Replace with your data
    return "Your resource content"

5. Replace the Example Prompts

@mcp.prompt()
def your_prompt(input_data: str) -> str:
    """Your prompt description"""
    # Replace with your prompt template
    return f"Your prompt template with {input_data}"

6. Update Data Models

Edit src/placeholder_package_name/models.py:

class YourDataModel(BaseModel):
    """Your domain-specific model"""
    id: str
    your_field: str
    # Add your specific fields

7. Update Tests

Edit tests/test_server.py to test your new functionality:

def test_your_custom_tool():
    result = your_custom_tool("test input")
    assert result["result"] == "Processed: test input"

8. Update Docker Configuration

Edit the Docker image name in your build commands and client configuration:

# Update the image name in build commands
docker build -t your-mcp-server:latest .  # Change from mcp-server-template

Update MCP client configuration with your server name:

{
  "mcpServers": {
    "your-server-name": {  // Change from "mcp-server-template"
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--name", "your-mcp-server",  // Change container name
        "your-mcp-server:latest"     // Change image name
      ]
    }
  }
}

Development Commands

# Install dependencies
make install

# Run tests
make test

# Format code
make format

# Run linting
make lint

# Run server
make run

# Run server with inspector (for debugging)
make dev

# Clean cache files
make clean

MCP Client Configuration

Local Development

Configure your MCP client to use this server locally:

{
  "mcpServers": {
    "PLACEHOLDER_SERVER_NAME": {
      "command": "uv",
      "args": ["run", "mcp", "run", "main.py"],
      "cwd": "/path/to/PLACEHOLDER_PROJECT_NAME"
    }
  }
}

Docker Configuration

For containerized deployments, configure your MCP client to use the Docker container:

{
  "mcpServers": {
    "PLACEHOLDER_SERVER_NAME": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--name", "placeholder-mcp-server",
        "placeholder-mcp-server:latest"
      ]
    }
  }
}

Important Docker Notes:

The --rm flag automatically removes the container when it exits
The -i flag keeps STDIN open for MCP communication
The --name flag assigns a name to the container for easier management
Build the image first with: docker build -t placeholder-mcp-server:latest .

Docker Usage

Build the Image

docker build -t placeholder-mcp-server:latest .

Development

docker-compose up PLACEHOLDER_SERVER_NAME-dev

Production

docker-compose up PLACEHOLDER_SERVER_NAME-prod

Manual Docker Run

# Run the server container directly
docker run --rm -i placeholder-mcp-server:latest

Server-Sent Events (SSE) Configuration

Local SSE Setup

Run the MCP server with SSE transport:

uv run mcp run main.py --transport sse --port 8000

Client Configuration

Configure your MCP client for SSE transport:

{
  "mcpServers": {
    "PLACEHOLDER_SERVER_NAME": {
      "transport": {
        "type": "sse",
        "url": "http://localhost:8000/sse"
      }
    }
  }
}

Docker SSE Setup

Use the provided SSE service in docker-compose.yml:

docker-compose up PLACEHOLDER_SERVER_NAME-sse

Or build and run directly:

docker build -t placeholder-mcp-server:latest .
docker run -p 8000:8000 placeholder-mcp-server:latest

Testing

Run the test suite:

make test

# Or with pytest directly
uv run pytest -v

The tests cover:

Tool functionality
Resource access
Prompt generation
Basic error handling

Next Steps

Replace the examples with your domain-specific tools, resources, and prompts
Add your business logic to the tool implementations
Create meaningful resources that provide value to LLM interactions
Design useful prompts for your specific use case
Expand the test suite to cover your custom functionality
Update documentation to reflect your server's capabilities

Support

License

MIT License - see LICENSE file for details.