mcp-forge
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
"The FastAPI moment for MCP servers."
⭐ What Is mcp-forge?
mcp-forge eliminates MCP server boilerplate entirely. You write a typed Python function. The framework derives the JSON Schema from your type hints, validates inputs at runtime, and exposes the tool over STDIO, HTTP, or SSE — without changing a single line of your logic.
Every MCP server starts the same way: hand-craft JSON Schema, wire a transport loop, handle notifications/initialized, redirect stderr, copy-paste validation logic. mcp-forge does all of that for you.
from mcp_forge import Forge
app = Forge(name="my-server", version="1.0.0")
@app.tool(description="Search the knowledge base")
async def search(query: str, limit: int = 10) -> list[dict]:
"""Returns ranked results for the given query."""
... # your logic here
if __name__ == "__main__":
app.run() # STDIO — Claude Desktop / Cursor / VS Code readyNo JSON Schema by hand. No transport boilerplate. No config files.
Related MCP server: Berry MCP Server
⚡ Core Doctrine
These are not features. These are design laws.
☔ Principle | 🔧 Implementation |
Schema is Derived, Never Written | Pydantic v2 generates full draft-07 JSON Schema from type hints — automatically |
Transport is a Runtime Concern | STDIO · HTTP · SSE — switch with one flag, tool code never changes |
Contrib is Opt-In |
|
Strict by Default | mypy strict + ruff + 100% typed public API — no surprises in production |
Testing Without a Server |
|
Zero Boilerplate |
|
🚀 Quick Start
# Install
pip install mcp-forge
# Scaffold + run
mcp-forge new my-server && cd my-server
mcp-forge run --reloadConnect to Claude Desktop in 30 seconds:
{
"mcpServers": {
"my-server": {
"command": "python",
"args": ["-m", "my_server"]
}
}
}Switch to HTTP transport with one flag:
mcp-forge run --transport http --port 8080✨ Features
Feature | Description |
🏗️ Declarative Tools |
|
🧠 Auto JSON Schema | Pydantic v2 under the hood — full draft-07 generated from type hints |
✅ Runtime Validation | Inputs validated before execution — errors as proper MCP-spec responses |
🚀 Multi-Transport | STDIO · HTTP · SSE — switch at runtime, logic unchanged |
⏳ Async-First |
|
🔌 Contrib Routers |
|
🧪 Testing Client |
|
📦 PEP 561 Typed | Ships |
📚 Examples
Minimal server
from mcp_forge import Forge
app = Forge(name="calculator")
@app.tool()
def add(a: float, b: float) -> float:
"""Add two numbers."""
return a + b
app.run()With contrib tools
from mcp_forge import Forge
from mcp_forge.contrib import memory, filesystem, web
app = Forge(name="agent-tools")
app.include(memory) # remember(), recall(), forget(), list_memory()
app.include(filesystem) # read_file(), write_file(), list_dir(), delete_file()
app.include(web) # fetch_url()
app.run()Unit testing — no server needed
from mcp_forge.testing import ForgeTestClient
client = ForgeTestClient(app)
def test_add():
result = client.call("add", {"a": 2, "b": 3})
assert result == 5🏗️ Architecture
Claude Desktop / Cursor / VS Code / Custom LLM Agents
│
├──► STDIO JSON-RPC 2.0 (mcp-forge run)
└──► HTTP / SSE Transport (mcp-forge run --transport http|sse)
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ mcp-forge │
│ │
│ ┌───────────────────┐ ┌───────────────────┐ ┌─────────────────┐ │
│ │ Declarative @tool │ │ Pydantic v2 │ │ Runtime │ │
│ │ Registry │─►│ Auto-Schema │─►│ Validator │ │
│ │ • Sync & Async │ │ • Draft-07 JSON │ │ • Input Guard │ │
│ │ • Contrib Routers │ │ • Type Coercion │ │ • Output Guard │ │
│ └───────────────────┘ └───────────────────┘ └─────────────────┘ │
│ │
│ ┌───────────────────┐ ┌───────────────────┐ ┌─────────────────┐ │
│ │ Transport Layer │ │ In-Process │ │ Live Telemetry │ │
│ │ • STDIO / HTTP │ │ ForgeTestClient │ │ & Doctor / │ │
│ │ • SSE Streaming │ │ • Zero-Socket │ │ Bench Matrix │ │
│ └───────────────────┘ └───────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│ │
▼ ▼
Typed Tool Execution MCP Spec 2024-11-05
(memory / filesystem / web) Structured Responses📁 Project Structure
mcp-forge/
├── mcp_forge/
│ ├── __init__.py # Public Forge, ForgeConfig & exception exports
│ ├── py.typed # PEP 561 strict typing marker
│ ├── core/
│ │ ├── config.py # ForgeConfig dataclass
│ │ ├── exceptions.py # MCP-aligned exception hierarchy
│ │ ├── forge.py # Declarative Forge app & @app.tool() registry
│ │ ├── schema.py # Auto JSON Schema (draft-07) from Pydantic v2
│ │ └── validator.py # Runtime input/output validation engine
│ ├── serve/
│ │ ├── __init__.py # Serving & telemetry subpackage exports
│ │ └── telemetry.py # P50/P90/P99 latency & tool call metrics
│ ├── tools/
│ │ ├── __init__.py # Diagnostics & benchmark subpackage exports
│ │ ├── bench_matrix.py # Multi-batch tool dispatch benchmark matrix
│ │ └── doctor.py # Runtime dependency & schema probe
│ ├── transports/
│ │ ├── __init__.py # Transport exports
│ │ ├── http.py # FastAPI-based HTTP REST transport
│ │ ├── sse.py # Server-Sent Events streaming transport
│ │ └── stdio.py # STDIO JSON-RPC 2.0 transport
│ ├── cli/
│ │ ├── main.py # Typer CLI (new, run, validate, build)
│ │ └── validator.py # CLI schema & manifest validator
│ ├── contrib/
│ │ ├── __init__.py # Opt-in contrib router exports
│ │ ├── filesystem.py # Sandboxed filesystem tools
│ │ ├── memory.py # Scoped in-process memory store
│ │ └── web.py # Resilient HTTP fetch tool
│ └── testing/
│ ├── __init__.py # Testing client exports
│ └── client.py # Zero-socket in-process ForgeTestClient
├── docs/
│ └── ARCHITECTURE.md # Framework & subpackage architecture spec
├── examples/
│ ├── contrib_router_demo.py # Contrib memory router + TelemetryEngine demo
│ └── quickstart_server.py # Minimal Forge app + ForgeTestClient example
├── scripts/
│ ├── benchmark_dispatch.py # Tool dispatch throughput benchmark runner
│ └── gate_schema_validation.py # Pydantic v2 strict validation gate script
└── tests/ # Full pytest suite (29 tests)📦 Installation
# Core only (STDIO transport)
pip install mcp-forge
# With HTTP + SSE transports
pip install "mcp-forge[http]"
# Everything
pip install "mcp-forge[all]"Requires: Python 3.11+ · pydantic>=2.0
🌍 Ecosystem Compatibility
Client | Transport | Status |
Claude Desktop | STDIO | ✅ Tested |
Cursor | STDIO | ✅ Tested |
VS Code (GitHub Copilot) | STDIO · HTTP | ✅ Tested |
Continue.dev | HTTP · SSE | ✅ Tested |
Custom LLM agents | HTTP · SSE | ✅ Tested |
🤝 Contributing
Contributions are welcome. See CONTRIBUTING.md for the full guide.
git clone https://github.com/benni-os/mcp-forge
cd mcp-forge
pip install -e ".[dev]"
pytest🐛 Found a bug? → Open an issue
💡 Have an idea? → Start a discussion
📜 See what's planned → ROADMAP.md
🌐 The Benni OS Open-Source Ecosystem
mcp-forge is part of the coordinated Benni Master OS v9.4 open-source infrastructure suite:
Repository | Focus & Architecture | Stars |
Zero-Dependency Spec-Driven Development, Static AST Drift Detector & MCP Guardrail | ||
High-Throughput Sovereign Local Inference for 8GB–16GB Consumer GPUs | ||
Deterministic Zero-Cloud Agent Evaluation, Red-Teaming & Benchmark Harness | ||
Micro-Second Zero-Dependency Code Sandbox & Execution Shield for AI Agents | ||
Autonomous Multi-Source Deep Research & Evidence Synthesis Engine | ||
Token-Saving Resilient Headless Browser Automation & A11y DOM Compiler | ||
Deterministic Intent Compiler & Typed DAG Execution Planner for AI Agents | ||
Sub-Millisecond Context Compression & Semantic Deduplication Engine | ||
Real-Time Biometric Swarm Governance & 120 FPS Resonant Kinetic Interface | ||
Zero-Trust Runtime Security, Prompt Injection Firewall & Secrets Redaction | ||
Deterministic Multi-Step Task Execution Ledger & Anti-Looping Engine | ||
Cryptographic State Verification & Invariant Proof Engine for Agents | ||
Hybrid Vector + BM25 Hierarchical Session Memory & Continuity Engine | ||
Human-in-the-Loop Approval & Policy Enforcement Gateway | ||
Rapid Model Context Protocol (MCP) Server Scaffolding & Dynamic Tooling | ||
Autonomous Multi-Agent Intent Routing & Swarm Coordination Hub | ||
Autonomous GitHub Community Triaging & PR Feedback Agent |
🏛️ Commercial & Sovereign Architecture
Need autonomous multi-agent swarm orchestration, private datacenter infrastructure, or enterprise governance?
Official Website: https://benni-os.net
Operator Mode Playbook: https://benni-os.net/blog/academy.html
GitHub Organization: https://github.com/Benni-OS
Maintainer: Benni Alencar
📄 License & Provenance
License: MIT License
Author: Benni Alencar (
bennialencar@benni-os.net)Architecture: Benni Master OS v9.4 Tier-0 Governance Standard
mcp-forge — Open-Source Python MCP Framework by Benni OS • benni-os.net • MIT License
ZERO_BOILERPLATE • AUTO_SCHEMA • MULTI_TRANSPORT • STRICT_TYPING • MIT_LICENSE
Engineered by Benni Alencar and the Benni OS Core Engineering Group · If mcp-forge saves you time, give it a ⭐
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Primarily to be used as a template repository for developing MCP servers with FastMCP in Python, P…
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA production-ready MCP server built with FastAPI, providing an enhanced tool registry for creating, managing, and documenting AI tools for Large Language Models (LLMs).34-
- AlicenseNot gradedqualityDmaintenanceA universal framework for creating and deploying custom Model Context Protocol (MCP) tool servers with decorator-based tool registration, supporting multiple transports and automatic JSON schema generation for AI assistants.2MIT
- AlicenseBqualityDmaintenanceA Python library to build MCP servers with decorators, auto-generating JSON Schema from type hints and including built-in filesystem and HTTP servers.3MIT
- FlicenseNot gradedqualityDmaintenanceA Python-based MCP server that exposes tools over streamable HTTP using FastAPI, enabling connection to AI assistants like Cursor. Supports multiple servers mounted in a single FastAPI app.-