Simply-MCP-PY

A modern, Pythonic framework for building Model Context Protocol (MCP) servers with multiple API styles

Simply-MCP-PY is the Python implementation of simply-mcp-ts, bringing the same ease-of-use and flexibility to the Python ecosystem for building MCP servers.

Features

• Multiple API Styles - Choose the style that fits your workflow:

  • 🎨 Decorator API - Clean, declarative class-based approach
  • 🔧 Functional API - Programmatic server building with method chaining
  • 📝 Interface API - Pure type-annotated interfaces (coming soon)
  • 🤖 Builder API - AI-powered tool development (future)

• Multiple Transports - Run your server anywhere:

  • 📟 Stdio - Standard input/output (default)
  • 🌐 HTTP - RESTful HTTP server with session support
  • 📡 SSE - Server-Sent Events for real-time streaming

• Zero Configuration - Get started instantly:

  • Auto-detect API style
  • Automatic schema generation from type hints
  • Sensible defaults for everything
  • Optional configuration for advanced use cases

• Developer Experience:

  • 🔥 Hot reload with watch mode
  • 📦 Bundle to standalone executable
  • 🎯 Type-safe with full mypy support
  • 📚 Comprehensive documentation

• Production Ready:

  • 🔒 Rate limiting and authentication
  • ⚡ Progress reporting for long operations
  • 🔄 Lifespan management with startup/shutdown hooks
  • 📊 Binary content support
  • 🛡️ Security best practices

Quick Start

Installation

Option 1: Try without installing (uvx)

# Install uvx
pip install uv

# Run directly without installing simply-mcp
uvx simply-mcp --version
uvx simply-mcp run server.py

Option 2: Install permanently (pip)

pip install simply-mcp

Your First Server (Decorator API)

# server.py
from simply_mcp import mcp_server, tool

@mcp_server(name="my-server", version="1.0.0")
class MyServer:
    @tool(description="Add two numbers")
    def add(self, a: int, b: int) -> int:
        """Add two numbers together."""
        return a + b

    @tool(description="Greet a user")
    def greet(self, name: str, formal: bool = False) -> str:
        """Generate a greeting."""
        if formal:
            return f"Good day, {name}."
        return f"Hey {name}!"

Run Your Server

# Run with stdio (default)
simply-mcp run server.py

# Run with HTTP on port 3000
simply-mcp run server.py --transport http --port 3000

# Run with auto-reload
simply-mcp run server.py --watch

Note: If using uvx, prefix commands with uvx: uvx simply-mcp run server.py. First run takes ~7-30 seconds to download packages, subsequent runs are near-instant.

API Styles

Decorator API (Recommended)

Clean, declarative class-based approach:

from simply_mcp import mcp_server, tool, prompt, resource

@mcp_server(name="my-server", version="1.0.0")
class MyServer:
    @tool(description="Calculate sum")
    def add(self, a: int, b: int) -> int:
        return a + b

    @prompt(description="Generate code review")
    def code_review(self, language: str) -> str:
        return f"Please review this {language} code..."

    @resource(uri="config://server", mime_type="application/json")
    def get_config(self) -> dict:
        return {"status": "running", "version": "1.0.0"}

Functional API

Programmatic server building:

from simply_mcp import BuildMCPServer

mcp = BuildMCPServer(name="my-server", version="1.0.0")

@mcp.add_tool(description="Add two numbers")
def add(a: int, b: int) -> int:
    return a + b

@mcp.add_prompt(description="Generate greeting")
def greet(name: str) -> str:
    return f"Hello, {name}!"

# Method chaining
mcp.configure(port=3000).run()

Configuration

Create a simplymcp.config.toml file:

[server]
name = "my-mcp-server"
version = "1.0.0"

[transport]
type = "http"  # or "stdio", "sse"
port = 3000

[logging]
level = "INFO"
format = "json"

[security]
enable_rate_limiting = true
rate_limit_per_minute = 60

Or use environment variables:

export SIMPLY_MCP_TRANSPORT=http
export SIMPLY_MCP_PORT=3000
export SIMPLY_MCP_LOG_LEVEL=DEBUG

Advanced Features

Lifespan Management

from simply_mcp import BuildMCPServer, Context

mcp = BuildMCPServer(name="my-server", version="1.0.0")

@mcp.on_startup()
async def initialize():
    """Run on server startup - load resources, connect to databases, etc."""
    db = await create_database_connection()
    mcp.server.lifespan['db'] = db  # Store for later use

@mcp.on_shutdown()
async def cleanup():
    """Run on server shutdown - close connections, save state, etc."""
    db = mcp.server.lifespan.get('db')
    if db:
        await db.close()

@mcp.tool()
async def query_data(query: str, ctx: Context) -> dict:
    """Access lifespan state in request handlers."""
    db = ctx.request_context.lifespan_context['db']
    result = await db.query(query)
    return result

Progress Reporting

from simply_mcp import tool, Progress

@tool(description="Process large dataset")
async def process_data(data: list, progress: Progress) -> dict:
    total = len(data)
    for i, item in enumerate(data):
        await progress.update(
            percentage=(i / total) * 100,
            message=f"Processing item {i+1}/{total}"
        )
        # Process item...
    return {"processed": total}

Authentication

# simplymcp.config.toml
[security.auth]
enabled = true
type = "api_key"
api_keys = ["your-secret-key"]

Binary Content

@resource(uri="file://document.pdf", mime_type="application/pdf")
def get_document(self) -> bytes:
    with open("document.pdf", "rb") as f:
        return f.read()

CLI Commands

# Run a server
simply-mcp run server.py [--transport TYPE] [--port PORT] [--watch]

# Bundle to executable
simply-mcp bundle server.py --output dist/

# List available servers
simply-mcp list [--json]

# Configuration management
simply-mcp config init          # Create config file
simply-mcp config validate      # Validate config
simply-mcp config show          # Show current config

Examples

Check out the examples/ directory:

• simple_server.py - Minimal working example
• decorator_basic.py - Decorator API basics
• functional_api.py - Functional API usage
• http_server.py - HTTP transport example
• lifespan_management_example.py - Startup/shutdown hooks, state management
• advanced_features.py - Progress, auth, binary content

Documentation

• Technical Specification - Detailed technical specs
• Architecture - System architecture
• Implementation Roadmap - Development plan
• API Reference - Complete API docs
• Migration Guide - Coming from simply-mcp-ts?

Comparison with simply-mcp-ts

Feature	simply-mcp-ts	simply-mcp-py
Decorator API	✅	✅
Functional API	✅	✅
Interface API	✅	🚧 (planned)
Builder API	✅	🚧 (future)
Stdio Transport	✅	✅
HTTP Transport	✅	✅
SSE Transport	✅	✅
Watch Mode	✅	✅
Bundling	✅	✅
Schema Validation	Zod	Pydantic
Type System	TypeScript	Python + mypy

Development Status

✅ v0.1.0 Stable Release - Production ready. Core features are fully implemented and tested. The API is stable and suitable for production use. See ROADMAP.md for planned features in future versions.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Requirements

• Python 3.10 or higher
• Dependencies managed via pip

License

MIT License - see LICENSE file for details.

Related Projects

• simply-mcp-ts - TypeScript version
• Anthropic MCP SDK - Official Python MCP SDK
• Model Context Protocol - Protocol specification

Acknowledgments

• Built on top of the Anthropic MCP Python SDK
• Inspired by simply-mcp-ts
• Created by Clockwork Innovations

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

---

Made with ❤️ by Clockwork Innovations