# Simply-MCP-PY
> A modern, Pythonic framework for building Model Context Protocol (MCP) servers with multiple API styles
[](https://www.python.org/downloads/)
[](LICENSE)
[]()
Simply-MCP-PY is the Python implementation of [simply-mcp-ts](https://github.com/Clockwork-Innovations/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
- 📊 Binary content support
- 🛡️ Security best practices
## Quick Start
### Installation
**Option 1: Try without installing (uvx)**
```bash
# 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)**
```bash
pip install simply-mcp
```
### Your First Server (Decorator API)
```python
# 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
```bash
# 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:
```python
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:
```python
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:
```toml
[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:
```bash
export SIMPLY_MCP_TRANSPORT=http
export SIMPLY_MCP_PORT=3000
export SIMPLY_MCP_LOG_LEVEL=DEBUG
```
## Advanced Features
### Progress Reporting
```python
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
```python
# simplymcp.config.toml
[security.auth]
enabled = true
type = "api_key"
api_keys = ["your-secret-key"]
```
### Binary Content
```python
@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
```bash
# 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
- `advanced_features.py` - Progress, auth, binary content
## Documentation
- [Technical Specification](docs/TECHNICAL_SPEC.md) - Detailed technical specs
- [Architecture](docs/ARCHITECTURE.md) - System architecture
- [Implementation Roadmap](docs/ROADMAP.md) - Development plan
- [API Reference](https://simply-mcp-py.readthedocs.io) - Complete API docs
- [Migration Guide](docs/migration-from-typescript.md) - 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
🚧 **Currently in Alpha** - Core features are implemented and functional, but the API may change. See [ROADMAP.md](docs/ROADMAP.md) for development progress.
## Contributing
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## Requirements
- Python 3.10 or higher
- Dependencies managed via pip
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Related Projects
- [simply-mcp-ts](https://github.com/Clockwork-Innovations/simply-mcp-ts) - TypeScript version
- [Anthropic MCP SDK](https://github.com/modelcontextprotocol/python-sdk) - Official Python MCP SDK
- [Model Context Protocol](https://modelcontextprotocol.io) - Protocol specification
## Acknowledgments
- Built on top of the [Anthropic MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- Inspired by [simply-mcp-ts](https://github.com/Clockwork-Innovations/simply-mcp-ts)
- Created by [Clockwork Innovations](https://clockwork-innovations.com)
## Support
- 📖 [Documentation](https://simply-mcp-py.readthedocs.io)
- 🐛 [Issue Tracker](https://github.com/Clockwork-Innovations/simply-mcp-py/issues)
- 💬 [Discussions](https://github.com/Clockwork-Innovations/simply-mcp-py/discussions)
---
**Made with ❤️ by Clockwork Innovations**
Raw data
{
"_id": null,
"home_page": null,
"name": "simply-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, anthropic, framework, llm, mcp, model-context-protocol, server",
"author": null,
"author_email": "Clockwork Innovations <info@clockwork-innovations.com>",
"download_url": "https://files.pythonhosted.org/packages/2b/f5/a5b547964b56172d47a46d592d307dad105a28ad4941571a82580f10891e/simply_mcp-0.1.0.tar.gz",
"platform": null,
"description": "# Simply-MCP-PY\n\n> A modern, Pythonic framework for building Model Context Protocol (MCP) servers with multiple API styles\n\n[](https://www.python.org/downloads/)\n[](LICENSE)\n[]()\n\nSimply-MCP-PY is the Python implementation of [simply-mcp-ts](https://github.com/Clockwork-Innovations/simply-mcp-ts), bringing the same ease-of-use and flexibility to the Python ecosystem for building MCP servers.\n\n## Features\n\n- **Multiple API Styles** - Choose the style that fits your workflow:\n - \ud83c\udfa8 **Decorator API** - Clean, declarative class-based approach\n - \ud83d\udd27 **Functional API** - Programmatic server building with method chaining\n - \ud83d\udcdd **Interface API** - Pure type-annotated interfaces (coming soon)\n - \ud83e\udd16 **Builder API** - AI-powered tool development (future)\n\n- **Multiple Transports** - Run your server anywhere:\n - \ud83d\udcdf **Stdio** - Standard input/output (default)\n - \ud83c\udf10 **HTTP** - RESTful HTTP server with session support\n - \ud83d\udce1 **SSE** - Server-Sent Events for real-time streaming\n\n- **Zero Configuration** - Get started instantly:\n - Auto-detect API style\n - Automatic schema generation from type hints\n - Sensible defaults for everything\n - Optional configuration for advanced use cases\n\n- **Developer Experience**:\n - \ud83d\udd25 Hot reload with watch mode\n - \ud83d\udce6 Bundle to standalone executable\n - \ud83c\udfaf Type-safe with full mypy support\n - \ud83d\udcda Comprehensive documentation\n\n- **Production Ready**:\n - \ud83d\udd12 Rate limiting and authentication\n - \u26a1 Progress reporting for long operations\n - \ud83d\udcca Binary content support\n - \ud83d\udee1\ufe0f Security best practices\n\n## Quick Start\n\n### Installation\n\n**Option 1: Try without installing (uvx)**\n```bash\n# Install uvx\npip install uv\n\n# Run directly without installing simply-mcp\nuvx simply-mcp --version\nuvx simply-mcp run server.py\n```\n\n**Option 2: Install permanently (pip)**\n```bash\npip install simply-mcp\n```\n\n### Your First Server (Decorator API)\n\n```python\n# server.py\nfrom simply_mcp import mcp_server, tool\n\n@mcp_server(name=\"my-server\", version=\"1.0.0\")\nclass MyServer:\n @tool(description=\"Add two numbers\")\n def add(self, a: int, b: int) -> int:\n \"\"\"Add two numbers together.\"\"\"\n return a + b\n\n @tool(description=\"Greet a user\")\n def greet(self, name: str, formal: bool = False) -> str:\n \"\"\"Generate a greeting.\"\"\"\n if formal:\n return f\"Good day, {name}.\"\n return f\"Hey {name}!\"\n```\n\n### Run Your Server\n\n```bash\n# Run with stdio (default)\nsimply-mcp run server.py\n\n# Run with HTTP on port 3000\nsimply-mcp run server.py --transport http --port 3000\n\n# Run with auto-reload\nsimply-mcp run server.py --watch\n```\n\n**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.\n\n## API Styles\n\n### Decorator API (Recommended)\n\nClean, declarative class-based approach:\n\n```python\nfrom simply_mcp import mcp_server, tool, prompt, resource\n\n@mcp_server(name=\"my-server\", version=\"1.0.0\")\nclass MyServer:\n @tool(description=\"Calculate sum\")\n def add(self, a: int, b: int) -> int:\n return a + b\n\n @prompt(description=\"Generate code review\")\n def code_review(self, language: str) -> str:\n return f\"Please review this {language} code...\"\n\n @resource(uri=\"config://server\", mime_type=\"application/json\")\n def get_config(self) -> dict:\n return {\"status\": \"running\", \"version\": \"1.0.0\"}\n```\n\n### Functional API\n\nProgrammatic server building:\n\n```python\nfrom simply_mcp import BuildMCPServer\n\nmcp = BuildMCPServer(name=\"my-server\", version=\"1.0.0\")\n\n@mcp.add_tool(description=\"Add two numbers\")\ndef add(a: int, b: int) -> int:\n return a + b\n\n@mcp.add_prompt(description=\"Generate greeting\")\ndef greet(name: str) -> str:\n return f\"Hello, {name}!\"\n\n# Method chaining\nmcp.configure(port=3000).run()\n```\n\n## Configuration\n\nCreate a `simplymcp.config.toml` file:\n\n```toml\n[server]\nname = \"my-mcp-server\"\nversion = \"1.0.0\"\n\n[transport]\ntype = \"http\" # or \"stdio\", \"sse\"\nport = 3000\n\n[logging]\nlevel = \"INFO\"\nformat = \"json\"\n\n[security]\nenable_rate_limiting = true\nrate_limit_per_minute = 60\n```\n\nOr use environment variables:\n\n```bash\nexport SIMPLY_MCP_TRANSPORT=http\nexport SIMPLY_MCP_PORT=3000\nexport SIMPLY_MCP_LOG_LEVEL=DEBUG\n```\n\n## Advanced Features\n\n### Progress Reporting\n\n```python\nfrom simply_mcp import tool, Progress\n\n@tool(description=\"Process large dataset\")\nasync def process_data(data: list, progress: Progress) -> dict:\n total = len(data)\n for i, item in enumerate(data):\n await progress.update(\n percentage=(i / total) * 100,\n message=f\"Processing item {i+1}/{total}\"\n )\n # Process item...\n return {\"processed\": total}\n```\n\n### Authentication\n\n```python\n# simplymcp.config.toml\n[security.auth]\nenabled = true\ntype = \"api_key\"\napi_keys = [\"your-secret-key\"]\n```\n\n### Binary Content\n\n```python\n@resource(uri=\"file://document.pdf\", mime_type=\"application/pdf\")\ndef get_document(self) -> bytes:\n with open(\"document.pdf\", \"rb\") as f:\n return f.read()\n```\n\n## CLI Commands\n\n```bash\n# Run a server\nsimply-mcp run server.py [--transport TYPE] [--port PORT] [--watch]\n\n# Bundle to executable\nsimply-mcp bundle server.py --output dist/\n\n# List available servers\nsimply-mcp list [--json]\n\n# Configuration management\nsimply-mcp config init # Create config file\nsimply-mcp config validate # Validate config\nsimply-mcp config show # Show current config\n```\n\n## Examples\n\nCheck out the `examples/` directory:\n\n- `simple_server.py` - Minimal working example\n- `decorator_basic.py` - Decorator API basics\n- `functional_api.py` - Functional API usage\n- `http_server.py` - HTTP transport example\n- `advanced_features.py` - Progress, auth, binary content\n\n## Documentation\n\n- [Technical Specification](docs/TECHNICAL_SPEC.md) - Detailed technical specs\n- [Architecture](docs/ARCHITECTURE.md) - System architecture\n- [Implementation Roadmap](docs/ROADMAP.md) - Development plan\n- [API Reference](https://simply-mcp-py.readthedocs.io) - Complete API docs\n- [Migration Guide](docs/migration-from-typescript.md) - Coming from simply-mcp-ts?\n\n## Comparison with simply-mcp-ts\n\n| Feature | simply-mcp-ts | simply-mcp-py |\n|---------|--------------|---------------|\n| Decorator API | \u2705 | \u2705 |\n| Functional API | \u2705 | \u2705 |\n| Interface API | \u2705 | \ud83d\udea7 (planned) |\n| Builder API | \u2705 | \ud83d\udea7 (future) |\n| Stdio Transport | \u2705 | \u2705 |\n| HTTP Transport | \u2705 | \u2705 |\n| SSE Transport | \u2705 | \u2705 |\n| Watch Mode | \u2705 | \u2705 |\n| Bundling | \u2705 | \u2705 |\n| Schema Validation | Zod | Pydantic |\n| Type System | TypeScript | Python + mypy |\n\n## Development Status\n\n\ud83d\udea7 **Currently in Alpha** - Core features are implemented and functional, but the API may change. See [ROADMAP.md](docs/ROADMAP.md) for development progress.\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## Requirements\n\n- Python 3.10 or higher\n- Dependencies managed via pip\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Related Projects\n\n- [simply-mcp-ts](https://github.com/Clockwork-Innovations/simply-mcp-ts) - TypeScript version\n- [Anthropic MCP SDK](https://github.com/modelcontextprotocol/python-sdk) - Official Python MCP SDK\n- [Model Context Protocol](https://modelcontextprotocol.io) - Protocol specification\n\n## Acknowledgments\n\n- Built on top of the [Anthropic MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)\n- Inspired by [simply-mcp-ts](https://github.com/Clockwork-Innovations/simply-mcp-ts)\n- Created by [Clockwork Innovations](https://clockwork-innovations.com)\n\n## Support\n\n- \ud83d\udcd6 [Documentation](https://simply-mcp-py.readthedocs.io)\n- \ud83d\udc1b [Issue Tracker](https://github.com/Clockwork-Innovations/simply-mcp-py/issues)\n- \ud83d\udcac [Discussions](https://github.com/Clockwork-Innovations/simply-mcp-py/discussions)\n\n---\n\n**Made with \u2764\ufe0f by Clockwork Innovations**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A modern Python framework for building MCP servers with multiple API styles",
"version": "0.1.0",
"project_urls": {
"Changelog": "https://github.com/Clockwork-Innovations/simply-mcp-py/blob/main/CHANGELOG.md",
"Documentation": "https://simply-mcp-py.readthedocs.io",
"Homepage": "https://github.com/Clockwork-Innovations/simply-mcp-py",
"Issues": "https://github.com/Clockwork-Innovations/simply-mcp-py/issues",
"Repository": "https://github.com/Clockwork-Innovations/simply-mcp-py"
},
"split_keywords": [
"ai",
" anthropic",
" framework",
" llm",
" mcp",
" model-context-protocol",
" server"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fe1e2abacbae58498cc8ef68dfa9ae46e6de1abfba313f4e3fbb01d6ea1d0fe6",
"md5": "b72fd177cd1263928d900df99b065c95",
"sha256": "7f9a6dcd0fd26f98deaaf0ad6c2bbd744758963a2a85fc1809ffc8533eb49e72"
},
"downloads": -1,
"filename": "simply_mcp-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b72fd177cd1263928d900df99b065c95",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 146553,
"upload_time": "2025-10-18T06:19:42",
"upload_time_iso_8601": "2025-10-18T06:19:42.178123Z",
"url": "https://files.pythonhosted.org/packages/fe/1e/2abacbae58498cc8ef68dfa9ae46e6de1abfba313f4e3fbb01d6ea1d0fe6/simply_mcp-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2bf5a5b547964b56172d47a46d592d307dad105a28ad4941571a82580f10891e",
"md5": "10d8fc0836810674081accf2031f0f88",
"sha256": "c27d654ea47cf23044932a176698f51be0a3723b847ac9f78a480adaaf11c182"
},
"downloads": -1,
"filename": "simply_mcp-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "10d8fc0836810674081accf2031f0f88",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 735832,
"upload_time": "2025-10-18T06:19:43",
"upload_time_iso_8601": "2025-10-18T06:19:43.615654Z",
"url": "https://files.pythonhosted.org/packages/2b/f5/a5b547964b56172d47a46d592d307dad105a28ad4941571a82580f10891e/simply_mcp-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-18 06:19:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Clockwork-Innovations",
"github_project": "simply-mcp-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "simply-mcp"
}
JSON
