modelcontextprotocol 1.0.0

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

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

🤝 Contributing

Contributions are welcome! This package helps developers:

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

📦 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 with ❤️ for the MCP community

# Get started now!
uvx modelcontextprotocol create