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

1. 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

2. Install dependencies:

uv sync

1. Create your environment file:

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

1. 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"}

1. Register the tool in server.py:

from .api import my_api

mcp.tool()(my_api.my_tool)

1. 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

Environment Variables

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