modelcontextprotocol

CLI tool and utilities for scaffolding Model Context Protocol (MCP) projects with enhanced logging

Create production-ready MCP servers and clients in seconds with built-in loguru logging and optional PostHog analytics.

Features

• Quick Scaffolding - Generate MCP projects instantly
• Enhanced Logging - Beautiful logs with loguru out of the box
• Analytics - Optional PostHog integration for usage tracking
• Beautiful CLI - Rich terminal UI with helpful prompts
• Best Practices - Templates follow MCP best practices
• uvx Compatible - No installation needed with uvx

Quick Start

With uvx (No Installation)

# Interactive mode
uvx modelcontextprotocol create

# Direct creation
uvx modelcontextprotocol create my-server --type server

With pip/uv

# Install
pip install modelcontextprotocol
# or
uv pip install modelcontextprotocol

# Create a project
modelcontextprotocol create
# or
mcp-create server my-weather-server

📖 Usage

Interactive Mode

Simply run without arguments for an interactive experience:

modelcontextprotocol create

You'll be prompted for:

• Project name
• Project type (server/client)
• Template type (basic/advanced)
• Project path

Command Line Mode

# Create a basic server
mcp-create server my-server

# Create an advanced server with PostHog
mcp-create server my-server \
  --template advanced \
  --posthog-key YOUR_KEY

# Create a client
mcp-create client my-client

# Specify custom path
mcp-create server my-server --path ./projects/my-server

Environment Variables

# PostHog configuration
export POSTHOG_API_KEY="your-api-key"
export POSTHOG_HOST="https://app.posthog.com"

# Now create with analytics
mcp-create server my-server --template advanced

Generated Project Structure

Basic Server

my-server/
├── server.py          # Main server file with loguru
├── pyproject.toml     # Project configuration
├── .gitignore         # Git ignore rules
└── README.md          # Project documentation

Server Code (Basic)

from mcp.server.fastmcp import FastMCP
from loguru import logger

# Configure logging
logger.add("my-server.log", rotation="10 MB", level="INFO")
logger.info("Initializing my-server MCP server")

# Initialize server
mcp = FastMCP("my-server")

@mcp.tool()
async def example_tool(text: str) -> str:
    """An example tool that processes text."""
    logger.info(f"Processing text: {text}")
    result = f"Processed: {text}"
    logger.debug(f"Result: {result}")
    return result

if __name__ == "__main__":
    logger.info("Starting my-server server")
    mcp.run()

Advanced Server Features

The advanced template includes:

• Error logging to separate file
• HTTP client integration with httpx
• PostHog analytics tracking (optional)
• Graceful shutdown handling
• Enhanced error tracking

Templates

Basic Template

Perfect for simple MCP servers:

• Loguru logging to file
• Example tool and resource
• Clean structure

Advanced Template

For production servers:

• Dual logging (info + errors)
• HTTP client with retry logic
• PostHog analytics integration
• Error tracking
• Graceful shutdown

Logging with Loguru

All generated projects use loguru for beautiful, structured logging:

logger.info("Information message")
logger.success("Success message")
logger.warning("Warning message")
logger.error("Error message")
logger.debug("Debug message")

Logs are automatically:

• Color-coded in terminal
• Saved to files with rotation
• Formatted consistently
• Performance optimized

PostHog Analytics (Optional)

Track your MCP server usage:

# Automatically included in advanced template
posthog.capture(
    distinct_id="server",
    event="tool_called",
    properties={"tool_name": "example_tool"}
)

Development

After creating your project:

cd my-server

# Create virtual environment
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -e .

# Run your server
python server.py

Examples

Create Weather Server

mcp-create server weather-server --template advanced
cd weather-server
# Edit server.py to add weather API integration
python server.py

Create Database Client

mcp-create client db-client
cd db-client
# Edit client.py to connect to your MCP server
python client.py

With Analytics

export POSTHOG_API_KEY="phc_..."
mcp-create server analytics-server --template advanced
# PostHog tracking automatically included

Telemetry

This tool collects anonymous usage analytics to improve the user experience. No personal information or project details are collected.

To disable telemetry:

export MODELCONTEXTPROTOCOL_TELEMETRY=false

See TELEMETRY.md for full details.

Contributing

Contributions are welcome! This package helps developers:

• Get started with MCP quickly
• Follow best practices
• Include production-ready logging
• Track usage metrics (anonymous, opt-out available)

Package Contents

• cli.py - CLI interface with rich prompts
• templates/ - Server and client templates
• analytics.py - PostHog integration
• Additional utilities for MCP development

Resources

• MCP Documentation
• MCP Python SDK
• Loguru Documentation
• PostHog Documentation

License

MIT License - See LICENSE file for details

Acknowledgments

• Built on top of the official MCP Python SDK
• Uses loguru for beautiful logging
• Inspired by create-react-app and similar scaffolding tools

---

Made for the MCP community

# Get started now!
uvx modelcontextprotocol create