Simply MCP Py
A modern, Pythonic framework for building Model Context Protocol (MCP) servers
Installation
npx simply-mcp-pyAsk AI about Simply MCP Py
Powered by Claude Β· Grounded in docs
I know everything about Simply MCP Py. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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 exampledecorator_basic.py- Decorator API basicsfunctional_api.py- Functional API usagehttp_server.py- HTTP transport examplelifespan_management_example.py- Startup/shutdown hooks, state managementadvanced_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
