⚡ mcp-forge

⚡ mcp-forge

The FastAPI-style framework for building MCP servers in Python.

Stop writing boilerplate MCP servers. mcp-forge lets you declare tools with a single decorator — schema, validation, and transport are handled automatically.

from mcp_forge import Forge

app = Forge(name="my-server", version="1.0.0")

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

if __name__ == "__main__":
    app.run()  # STDIO, HTTP or SSE — your choice

That's it. No JSON schema by hand. No transport boilerplate. No config files.

✨ Features

🚀 Quick Start

Install

pip install mcp-forge

Create a new server

mcp-forge new my-server
cd my-server
mcp-forge run --reload

Add your first tool

from mcp_forge import Forge
from pydantic import BaseModel

app = Forge(name="calculator", version="1.0.0")

class SearchInput(BaseModel):
    query: str
    limit: int = 10

@app.tool(description="Search the knowledge base")
async def search(params: SearchInput) -> list[dict]:
    # your logic here
    return [{"result": f"Result for {params.query}"}]

Run in different transports

# STDIO (for Claude Desktop, Cursor, VS Code)
mcp-forge run --transport stdio

# HTTP (for custom integrations)
mcp-forge run --transport http --port 8080

# SSE (for streaming)
mcp-forge run --transport sse --port 8080

📐 Architecture

mcp-forge
├── core/
│   ├── forge.py          # Main Forge class — app entrypoint
│   ├── schema.py         # Auto JSON Schema from type hints (Pydantic v2)
│   ├── validator.py      # Input/output validation engine
│   ├── config.py         # ForgeConfig dataclass
│   └── exceptions.py     # Exception hierarchy
├── transports/
│   ├── stdio.py          # STDIO transport (Claude Desktop compatible)
│   ├── http.py           # FastAPI-based HTTP transport
│   └── sse.py            # Server-Sent Events transport
├── cli/
│   └── main.py           # Typer CLI — new, run, build, list
└── contrib/
    ├── memory.py         # Built-in memory tool (isolated per-instance store)
    ├── filesystem.py     # Built-in filesystem tools (read, write, list, delete)
    └── web.py            # Built-in web fetch tool

🔌 Built-in Tools (contrib)

mcp-forge ships with production-ready contrib tools you can include in one line:

from mcp_forge import Forge
from mcp_forge.contrib import memory, filesystem, web

app = Forge(name="full-server")
app.include(memory)      # remember(), recall(), forget(), list_memory()
app.include(filesystem)  # read_file(), write_file(), list_dir(), path_exists(), delete_file()
app.include(web)         # fetch_url()

⚙️ Configuration

from mcp_forge import Forge, ForgeConfig

app = Forge(
    name="my-server",
    version="1.0.0",
    config=ForgeConfig(
        transport="http",
        port=8080,
        log_level="info",
        cors_origins=["*"],
        max_tool_timeout=30,
    )
)

Or via mcp-forge.toml:

[server]
name = "my-server"
version = "1.0.0"
transport = "http"
port = 8080
log_level = "info"

[tools]
max_timeout = 30
auto_reload = true

🧪 Testing

from mcp_forge.testing import ForgeTestClient

client = ForgeTestClient(app)

def test_add():
    result = client.call("add", {"a": 2, "b": 3})
    assert result == 5

# Inside async tests:
async def test_add_async():
    result = await client.acall("add", {"a": 2, "b": 3})
    assert result == 5

🌍 Ecosystem Compatibility

📦 Roadmap

• @tool decorator with auto-schema
• STDIO transport (MCP spec 2024-11-05)
• HTTP transport (FastAPI)
• SSE transport
• Pydantic v2 validation
• CLI (new, run, build)
• Contrib routers (memory, filesystem, web)
• PEP 561 py.typed marker
• Python 3.11 / 3.12 / 3.13 tested
• @resource decorator (MCP Resources spec)
• @prompt decorator (MCP Prompts spec)
• Plugin registry (community contrib tools)
• Docker one-liner deploy
• mcp-forge cloud (hosted MCP servers)

🤝 Contributing

PRs welcome. See CONTRIBUTING.md.

git clone https://github.com/nsfwbunny/mcp-forge
cd mcp-forge
pip install -e ".[dev]"
pytest

📄 License

MIT — see LICENSE.

Built with ⚡ by Benni Alencar