MCP Cookie Cutter

A powerful CLI tool and cookiecutter template for creating Model Context Protocol (MCP) servers. Get a fully-configured MCP server in seconds with a single command, then customize it for your API.

Features

🎯 CLI Tool: One command to generate your MCP server - pip install mcp-cookie-cutter && mcp-cookie-cutter
🚀 Quick Start: Generate a working MCP server in seconds
🐍 Python with FastMCP: Modern Python-based MCP servers with FastMCP framework
🔧 OpenAPI Auto-Generation: Automatically generates tools from OpenAPI/Swagger specs
🌐 Local & Remote: Support for STDIO (local) and Streamable HTTP (remote) transports
🔐 Authentication: Built-in templates for OAuth 2.1 and API key authentication
📦 Full-Featured: Auto-generated tools, prompts, and Pydantic models
📝 Easy Customization: Clear examples and guides for adding your API tools
⚡ Modern Tooling: Uses uv for package management and uvicorn for production
✅ Best Practices: Follows MCP specification and security guidelines

What You Get

Complete MCP server project structure
Intelligent OpenAPI parsing - See available API operations during generation
Example tool implementations (GET and POST)
Comprehensive CUSTOMIZATION.md guide
Authentication templates
Development environment setup
Claude Desktop integration instructions

Prerequisites

Python 3.10+ (required)

Installation & Usage

🎯 Option 1: CLI Tool (Recommended - Easiest!)

The fastest way to get started:

# Install the CLI tool
pip install mcp-cookie-cutter

# Generate your MCP server
mcp-cookie-cutter

# Or with specific options
mcp-cookie-cutter --no-input project_name="My API Server"

That's it! The CLI bundles everything you need.

🔧 Option 2: Use with Cookiecutter

If you prefer using cookiecutter directly:

# Install cookiecutter first
pip install cookiecutter

# Use the template from GitHub
cookiecutter gh:maheshmahadevan/mcp-cookie-cutter

Dependency Details

All dependencies are automatically installed with the CLI tool. If using cookiecutter directly:

cookiecutter (required) - Template generation engine
pyyaml (optional) - For parsing YAML OpenAPI specs
requests (optional) - For fetching OpenAPI specs from URLs
openapi-pydantic (optional) - For validating and parsing OpenAPI schemas with type safety
datamodel-code-generator (optional) - For generating Pydantic models

Without the optional dependencies, you can still generate MCP servers, but OpenAPI spec parsing and tool suggestions will not be available.

Quick Start

Step 1: Install and Run

Using CLI (recommended):

pip install mcp-cookie-cutter
mcp-cookie-cutter

Or using cookiecutter:

cookiecutter gh:maheshmahadevan/mcp-cookie-cutter

Step 2: Answer the Prompts

You'll be asked to configure:

Project name: Name of your MCP server
Project description: Brief description
Author information: Your name and email
OpenAPI spec path: (Optional) Path or URL to your OpenAPI/Swagger spec
Deployment type: Local (STDIO) or Remote (Streamable HTTP)
Server port: Port for remote deployment (default: 8000)
Authentication: None, API key, or OAuth 2.1
License: Choose from MIT, Apache-2.0, BSD-3-Clause, GPL-3.0, or Proprietary

Step 3: Customize Your Tools

The generated server includes example tools. Follow the CUSTOMIZATION.md guide to add your API endpoints.

Step 4: Run Your Server

Follow the setup instructions displayed after generation, or see the generated README.md.

What Gets Generated

Project Structure

my-mcp-server/
├── src/
│   └── my_mcp_server/
│       ├── server.py          # FastMCP server with auto-discovery
│       ├── tools/             # Individual tool files (auto-generated)
│       │   ├── __init__.py
│       │   ├── addPet.py      # Example: POST /pet
│       │   ├── getPetById.py  # Example: GET /pet/{petId}
│       │   └── ...
│       ├── prompts/           # Auto-generated prompts from OpenAPI
│       │   ├── __init__.py
│       │   └── pet_operations.py
│       └── models/            # Pydantic models from OpenAPI
│           ├── __init__.py
│           └── schemas.py
├── test_server.py         # Development testing with auto-reload
├── pyproject.toml         # Python project configuration
├── .env.example           # Environment variables template
├── Dockerfile             # Docker container configuration
├── docker-compose.yml     # Docker compose for easy deployment
├── README.md              # Generated documentation
├── CUSTOMIZATION.md       # Guide for adding custom tools
└── .gitignore

Features

OpenAPI Integration: Auto-generates tools, prompts, and Pydantic models from OpenAPI specs
FastMCP Framework: Modern Python MCP framework with decorator-based tool definitions
Transport Support:
- Local (STDIO): For Claude Desktop and local clients
- Remote (Streamable HTTP): Production-grade HTTP server with uvicorn
Authentication:
- None: Open access (local development only)
- API Key: Bearer token authentication
- OAuth 2.1: Standards-compliant OAuth with PKCE support
MCP Features:
- Tools: Auto-generated from OpenAPI operations (individual files per tool)
- Prompts: Auto-generated helpful prompts from API operations
- Models: Pydantic models from OpenAPI schemas
- Logging: Proper stderr logging (STDIO-safe)

OpenAPI/Swagger Integration

The template includes intelligent OpenAPI parsing that:

Loads your OpenAPI/Swagger specification (from file or URL)
Validates the spec using openapi-pydantic (if installed)
Extracts all available endpoints (GET, POST, PUT, DELETE, PATCH)
Displays operation details during generation

Supported OpenAPI Formats

OpenAPI 3.0/3.1 (JSON or YAML)
Swagger 2.0 (JSON or YAML)

Example OpenAPI Flow

# Provide your OpenAPI spec path when prompted
openapi_spec_path: https://petstore.swagger.io/v2/swagger.json

# The hook will scan and display:
✨ Found 20 available API operations:
----------------------------------------------------------------------
 1. POST   /pet                           - addPet
     Add a new pet to the store
 2. GET    /pet/{petId}                   - getPetById
     Find pet by ID
...
----------------------------------------------------------------------

💡 You can implement these as MCP tools in your generated server.

Configuration Examples

Local Server with No Auth

deployment_type: local
auth_mechanism: none
openapi_spec_path: https://petstore3.swagger.io/api/v3/openapi.json

Result: STDIO-based server for Claude Desktop with auto-generated tools

Remote Server with API Keys

deployment_type: remote
server_port: 9090
auth_mechanism: api_key
openapi_spec_path: https://petstore3.swagger.io/api/v3/openapi.json

Result: Streamable HTTP server with API key authentication and auto-generated tools

Remote Server with OAuth

deployment_type: remote
server_port: 8000
auth_mechanism: oauth2
openapi_spec_path: https://api.github.com/openapi.json

Result: Streamable HTTP server with OAuth 2.1 authentication

Best Practices

The generated servers follow MCP best practices:

Security:
- OAuth 2.1 recommended for public clients
- API keys for internal services
- Proper user consent flows
- Environment-based credential management
Transport:
- STDIO for local deployments (no network exposure)
- SSE for remote deployments (stateful connections)
- Proper logging to stderr (never stdout)
Error Handling:
- Comprehensive error messages
- Input validation
- Graceful degradation
Code Quality:
- Type hints (Python) / TypeScript types
- Linting and formatting configuration
- Testing setup included

Development

Customizing the Template

The template uses Jinja2 templating. Key files:

cookiecutter.json: Configuration options
hooks/pre_gen_project.py: Pre-generation validation and OpenAPI scanning
hooks/post_gen_project.py: Post-generation setup and cleanup
{{cookiecutter.project_slug}}/: Template files with Jinja2 syntax

Testing Your Template

# Generate a test project
cookiecutter . --no-input

# Or with specific values
cookiecutter . --no-input deployment_type=local auth_mechanism=none

# Test with OpenAPI spec
cookiecutter . --no-input \
  openapi_spec_path="https://petstore3.swagger.io/api/v3/openapi.json" \
  deployment_type="remote" \
  server_port="9090"

Testing Resources

Test your MCP Cookie Cutter template with these verified APIs that have OpenAPI 3.0 specifications:

1. Swagger Petstore ⭐ Recommended for Testing

OpenAPI Spec: https://petstore3.swagger.io/api/v3/openapi.json
Base URL: https://petstore3.swagger.io/api/v3
Auth: None required
Resources: Pets, Store, Users
Why: Gold standard for API testing, fully functional, no auth needed

2. JSONPlaceholder - Simple & Free

OpenAPI Spec: https://gist.githubusercontent.com/oshevtsov/7d17f88f74730ce9c95b6d7bb3e03c3d/raw/jsonplaceholder-openapi-3.0.yaml
Base URL: https://jsonplaceholder.typicode.com
Auth: None required
Resources: Posts, Comments, Albums, Photos, Todos, Users
Why: Free fake REST API, perfect for quick testing

3. GitHub REST API - Real-World Example

OpenAPI Spec: https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json
Base URL: https://api.github.com
Auth: Optional (higher rate limits with token)
Resources: Repos, Issues, Users, Pull Requests
Why: Real production API, comprehensive operations
Note: Very large spec (~15MB) - Pydantic model generation may fail, but tools will still be generated

4. Stripe API - Payment Processing

OpenAPI Spec: https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json
Base URL: https://api.stripe.com
Auth: API Key (free test mode available)
Resources: Payments, Customers, Products, Subscriptions
Why: Well-documented, production-grade API

5. APIs-guru Collection - 300+ Public APIs

Repository: https://github.com/APIs-guru/openapi-directory
Popular APIs:

Quick Test Commands

Using CLI tool (recommended):

# Install if you haven't already
pip install mcp-cookie-cutter

# Test with Petstore (just run and enter the OpenAPI URL when prompted)
mcp-cookie-cutter

# Or use with --no-input for automated testing
mcp-cookie-cutter --no-input \
  project_name="petstore_server" \
  openapi_spec_path="https://petstore3.swagger.io/api/v3/openapi.json" \
  deployment_type="remote" \
  server_port="9090" \
  auth_mechanism="none"

Or using cookiecutter directly:

# Test with Petstore
cookiecutter gh:maheshmahadevan/mcp-cookie-cutter \
  project_name="petstore_server" \
  openapi_spec_path="https://petstore3.swagger.io/api/v3/openapi.json" \
  deployment_type="remote" \
  server_port="9090" \
  auth_mechanism="none"

# Test with JSONPlaceholder
cookiecutter gh:maheshmahadevan/mcp-cookie-cutter \
  project_name="jsonplaceholder_server" \
  openapi_spec_path="https://gist.githubusercontent.com/oshevtsov/7d17f88f74730ce9c95b6d7bb3e03c3d/raw/jsonplaceholder-openapi-3.0.yaml" \
  deployment_type="remote" \
  server_port="9090" \
  auth_mechanism="none"

# Test with GitHub API (note: very large spec, may take a minute)
cookiecutter gh:maheshmahadevan/mcp-cookie-cutter \
  project_name="github_server" \
  openapi_spec_path="https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json" \
  deployment_type="remote" \
  server_port="9090" \
  auth_mechanism="api_key"

Self-Hosted Testing Options

Quick Docker Deploy - Petstore:

docker run -d -p 8080:8080 swaggerapi/petstore3:unstable
# OpenAPI spec available at: http://localhost:8080/api/v3/openapi.json

Prism Mock Server (Mock ANY OpenAPI spec):

npm install -g @stoplight/prism-cli
prism mock https://petstore3.swagger.io/api/v3/openapi.json
# Creates a mock API server on http://localhost:4010

Resources

Distribution

For End Users

The easiest way to use this tool is via PyPI:

# Install the CLI tool
pip install mcp-cookie-cutter

# Use it anywhere
mcp-cookie-cutter

For Teams

Share via PyPI (recommended):

# Team members simply install and use
pip install mcp-cookie-cutter
mcp-cookie-cutter

Or share via GitHub:

# Team members use directly from GitHub
cookiecutter gh:maheshmahadevan/mcp-cookie-cutter

For Developers

If you want to modify the template locally:

# Clone the repository
git clone https://github.com/maheshmahadevan/mcp-cookie-cutter.git
cd mcp-cookie-cutter

# Install in editable mode
pip install -e .

# Now the CLI uses your local version
mcp-cookie-cutter

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Test your changes
Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and questions:

Open an issue on GitHub
Check existing issues and discussions
Review the MCP documentation

Generate production-ready MCP servers in seconds!

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.github/workflows		.github/workflows
docs		docs
examples		examples
hooks		hooks
mcp_cookie_cutter		mcp_cookie_cutter
scripts		scripts
{{cookiecutter.project_slug}}		{{cookiecutter.project_slug}}
.gitignore		.gitignore
.pypirc.example		.pypirc.example
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
cookiecutter.json		cookiecutter.json
hook_requirements.txt		hook_requirements.txt
pyproject.toml		pyproject.toml
setup.py		setup.py

Folders and files

Latest commit

History

Repository files navigation

MCP Cookie Cutter

Features

What You Get

Prerequisites

Installation & Usage

🎯 Option 1: CLI Tool (Recommended - Easiest!)

🔧 Option 2: Use with Cookiecutter

Dependency Details

Quick Start

Step 1: Install and Run

Step 2: Answer the Prompts

Step 3: Customize Your Tools

Step 4: Run Your Server

What Gets Generated

Project Structure

Features

OpenAPI/Swagger Integration

Supported OpenAPI Formats

Example OpenAPI Flow

Configuration Examples

Local Server with No Auth

Remote Server with API Keys

Remote Server with OAuth

Best Practices

Development

Customizing the Template

Testing Your Template

Testing Resources

1. Swagger Petstore ⭐ Recommended for Testing

2. JSONPlaceholder - Simple & Free

3. GitHub REST API - Real-World Example

4. Stripe API - Payment Processing

5. APIs-guru Collection - 300+ Public APIs

Quick Test Commands

Self-Hosted Testing Options

Resources

Distribution

For End Users

For Teams

For Developers

Contributing

License

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages