# Skeleton MCP Server
A template project for building [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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](https://github.com/astral-sh/uv) package manager (recommended)
- Docker (optional, for containerized deployment)
### Installation
1. Clone this repository and rename it for your project:
```bash
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:
```bash
uv sync
```
4. Create your environment file:
```bash
cp .env.example .env
# Edit .env with your API credentials
```
5. Run the server:
```bash
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
```bash
uv run pytest -v
```
### Linting
```bash
uv run ruff check src/ tests/
uv run ruff format src/ tests/
```
### Building
```bash
uv build
```
## Adding Your Own Tools
1. Create a new module in `src/skeleton_mcp/api/`:
```python
# 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`:
```python
from .api import my_api
mcp.tool()(my_api.my_tool)
```
3. Add types in `types.py` if needed:
```python
class MyDataType(TypedDict):
field1: str
field2: int
```
## Docker Deployment
### Build and run with Docker Compose:
```bash
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`):
```json
{
"mcpServers": {
"skeleton-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--env-file",
"/path/to/your/.env",
"skeleton-mcp:latest"
]
}
}
}
```
Or for local development:
```json
{
"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