Skeleton MCP Server

A template project for building Model Context Protocol (MCP) servers. This skeleton provides a solid foundation with best practices, Docker support, and example implementations.

Features

• FastMCP framework for easy MCP server development
• Docker and Docker Compose support for containerized deployment
• VS Code Dev Container configuration for consistent development environments
• Example CRUD API implementation to demonstrate patterns
• Test suite with pytest
• Claude Code integration with custom commands

Quick Start

Prerequisites

• Python 3.10 or higher
• uv package manager (recommended)
• Docker (optional, for containerized deployment)

Installation

1. Clone this repository and rename it for your project:

git clone <this-repo> my-mcp-server
cd my-mcp-server

2. Rename the package:

   • Rename src/skeleton_mcp to src/your_project_name
   • Update pyproject.toml with your project name and metadata
   • Update imports in all Python files

3. Install dependencies:

uv sync

4. Create your environment file:

cp .env.example .env
# Edit .env with your API credentials

5. Run the server:

uv run skeleton-mcp

Project Structure

skeleton_mcp/
├── src/skeleton_mcp/
│   ├── __init__.py          # Package initialization
│   ├── server.py            # Main MCP server entry point
│   ├── client.py            # API client for backend communication
│   ├── types.py             # TypedDict definitions
│   ├── api/                  # API modules
│   │   ├── __init__.py
│   │   └── example.py       # Example CRUD operations
│   └── utils/               # Utility modules
│       └── __init__.py
├── tests/                   # Test suite
│   ├── conftest.py          # Pytest fixtures
│   ├── test_example_api.py  # API tests
│   └── test_server.py       # Server tests
├── docs/                    # Documentation
├── .claude/                 # Claude Code configuration
│   ├── commands/            # Custom slash commands
│   └── settings.local.json  # Permission settings
├── .devcontainer/           # VS Code dev container
├── Dockerfile               # Container image definition
├── docker-compose.yml       # Production compose file
├── docker-compose.devcontainer.yml  # Dev container compose
├── pyproject.toml           # Project configuration
├── CLAUDE.md               # Claude context documentation
└── README.md               # This file

Development

Running Tests

uv run pytest -v

Linting

uv run ruff check src/ tests/
uv run ruff format src/ tests/

Building

uv build

Adding Your Own Tools

1. Create a new module in src/skeleton_mcp/api/:

# src/skeleton_mcp/api/my_api.py

async def my_tool(param1: str, param2: int = 10) -> dict:
    """
    Description of what this tool does.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Description of return value
    """
    # Your implementation here
    return {"result": "success"}

2. Register the tool in server.py:

from .api import my_api

mcp.tool()(my_api.my_tool)

3. Add types in types.py if needed:

class MyDataType(TypedDict):
    field1: str
    field2: int

Docker Deployment

Build and run with Docker Compose:

docker compose up --build

For development with VS Code Dev Containers:

1. Open the project in VS Code
2. Install the "Dev Containers" extension
3. Click "Reopen in Container" when prompted

Claude Desktop Integration

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "skeleton-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "/path/to/your/.env",
        "skeleton-mcp:latest"
      ]
    }
  }
}

Or for local development:

{
  "mcpServers": {
    "skeleton-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/skeleton_mcp", "run", "skeleton-mcp"]
    }
  }
}

Available Tools

Tool	Description
health_check	Check server health and configuration status
list_items	List all items with filtering and pagination
get_item	Get a specific item by ID
create_item	Create a new item
update_item	Update an existing item
delete_item	Delete an item

Environment Variables

Variable	Description	Default
API_KEY	Your API key for authentication	(required)
API_BASE_URL	Base URL for the backend API	https://api.example.com/v1
API_TIMEOUT	Request timeout in seconds	30
DEBUG	Enable debug logging	false

License

MIT License - See LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request