Cookiecutter MCP UV Container

A cookiecutter template for quickly creating MCP (Model Context Protocol) servers with Apple container support.

Why Apple Containers?

Apple containers provide VM-level isolation with Docker-like simplicity:

• Superior Security: Each container runs in its own lightweight VM
• macOS Native: Deep integration with macOS frameworks
• On-Demand: Start/stop servers as needed (not constantly running)
• Resource Efficient: Less overhead than traditional VMs
• OCI Compatible: Works with existing container registries

Features

• 🚀 FastMCP server setup with example tools
• 🐳 Multi-stage Dockerfile for optimized containers
• 📦 UV package management
• 🔒 VM-level isolation with non-root container user
• 🌐 Multiple transport methods (stdio, streamable-http, sse)
• 🍎 Optimized for Apple Silicon
• 📝 Example calculator tools with typed parameters

Usage

Prerequisites

1. Install UV (if not already installed):

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. Install cookiecutter:

   uv tool install cookiecutter
   # or
   pip install cookiecutter
   

3. Install Apple/Container:

   Visit https://github.com/apple/container

Create a new project

# From local directory
cookiecutter /path/to/cookiecutter-mcp-uv-container

# From GitHub 
cookiecutter https://github.com/daviddrummond95/cookiecutter-mcp-uv-container

Template Variables

You'll be prompted for:

• project_name: Human-readable project name (e.g., "My Calculator MCP")
• project_slug: Package name (auto-generated from project_name)
• mcp_name: The MCP server name (e.g., "MyCalculatorMCP")
• description: Project description
• author_name: Your name
• author_email: Your email
• python_version: Python version (default: 3.13)
• mcp_version: MCP SDK version (default: 1.9.4)

Project Structure

After generation, your project will have:

my-mcp-server/
├── Dockerfile          # Multi-stage build for containers
├── pyproject.toml      # UV project configuration
├── hello.py            # MCP server implementation
├── QUICKSTART.md       # Quick start guide
└── .env.example        # Environment configuration

Next Steps

After creating your project:

1. Navigate to your project:

   cd my-mcp-server # or whatever you put as project-slug
   

2. Start Container System (first time only):

   container system start
   

3. Build Container:

   container build --tag my-mcp . # Replace my-mcp with whatever you want to name the container
   

4. Run MCP Server:

   # Interactive stdio mode
   container run --interactive my-mcp
   

5. Customize: Edit hello.py to add your own MCP tools

Claude Desktop Integration

For Claude Desktop, you have two options:

Option 1: Run locally without container (recommended for development)

{
  "mcpServers": {
    "My MCP Server (Local)": {
      "command": "uv",
      "args": ["run", "fastmcp", "/path/to/my-mcp-server/hello.py"]
    }
  }
}

Option 2: Use HTTP transport with container

Then configure Claude Desktop to connect via STDIO:

{
  "mcpServers": {
    "My MCP Server (Container)": {
      "command": "container",
   	 "args": ["run",  "--interactive", "my-mcp-container"]
    }
  }
}

Transport Options

The template supports multiple transport methods via environment variables:

• stdio: Default
• More in progress for flow from local-> cloud

Set via: MCP_TRANSPORT=<transport-type>

License

MIT