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

Clone this repository and rename it for your project:

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

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
Install dependencies:

uv sync

Create your environment file:

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

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

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

from .api import my_api mcp.tool()(my_api.my_tool)

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:

Open the project in VS Code
Install the "Dev Containers" extension
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

Fork the repository
Create a feature branch
Make your changes
Run tests and linting
Submit a pull request

Skeleton MCP Server

Skeleton MCP Server

Features

Quick Start

Prerequisites

Installation

Project Structure

Development

Running Tests

Linting

Building

Adding Your Own Tools

Docker Deployment

Build and run with Docker Compose:

For development with VS Code Dev Containers:

Claude Desktop Integration

Available Tools

Environment Variables

License

Contributing

Resources

New MCP Servers

Latest Blog Posts

MCP directory API