mcpforge
mcpforge is an MCP server for building and managing FastMCP 3.x servers from natural-language descriptions.
Generate a complete tested server from a plain-English description, with controls for language, transport, provider/model, OpenAPI input, auth, middleware, dry runs, and no-execute mode.
Plan a server’s tools and structure without generating code.
Update an existing generated server using a natural-language request.
Validate a generated server with syntax, lint, import, and pytest checks.
Inspect a generated server without executing it.
Check local prerequisites and provider readiness with doctor.
List generated mcpforge servers in a workspace, optionally recursively.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcpforge generate a server for managing tasks with due dates"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcpforge
One English sentence in. A tested, spec-free FastMCP 3.x server out.
mcpforge turns a plain-English description into a complete FastMCP 3.x MCP server — tools, Pydantic input validation, error handling, a pytest suite, run config, and client setup docs — all wired together and ready to inspect, validate, and install. There's no MCP schema or protocol boilerplate to hand-write: the sentence is the spec. You write it; Claude writes the implementation; mcpforge runs the generated test suite and validators before you ever run it.
⚡ 60-second start

You need Python 3.12+, uv, and an Anthropic API key.
uv tool install fastmcp-builder # or: pip install fastmcp-builder
export ANTHROPIC_API_KEY="your_anthropic_api_key"
mcpforge generate "A weather server that returns today's forecast for a city" -o weather-serverNo key yet? Try the demo.
mcpforge demoruns the real plan → generate → validate pipeline against a built-in recording and writes a complete, validated weather server — no API key, no spend. It's the fastest way to see exactly what mcpforge produces:uvx --from fastmcp-builder mcpforge demo
Bring your own key (BYOK). Generation runs on your Anthropic API key — mcpforge calls the Claude API directly and nothing is proxied through a hosted service. A single
generatemakes a few model calls (plan → server → tests), so a typical run costs roughly $0.05–$0.30 in API usage on the default model (claude-sonnet-4-6). That figure is an estimate — it scales with server complexity and your chosen model, and is not a live measurement. Everything that doesn't call the model —validate,inspect,list,doctor, andinit— is free.
That's the whole loop. mcpforge plans the tools, generates the code, then runs syntax, security, lint, import, and pytest checks against the result — so what lands in ./weather-server/ is already validated:
# weather-server/server.py (excerpt)
"""Weather forecast MCP server."""
from fastmcp import FastMCP
mcp = FastMCP("Weather")
# Illustrative lookup — describe a real source and mcpforge wires the call for you.
_FORECASTS: dict[str, dict] = {
"san francisco": {"high_c": 18, "low_c": 12, "summary": "Foggy"},
"denver": {"high_c": 24, "low_c": 9, "summary": "Clear"},
}
@mcp.tool
async def get_forecast(city: str) -> dict:
"""Return today's forecast for a city."""
key = city.strip().lower()
if key not in _FORECASTS:
raise ValueError(f"No forecast available for {city!r}")
return {"city": city, **_FORECASTS[key]}
if __name__ == "__main__":
mcp.run(transport="streamable-http")Every generation also produces test_server.py (a real pytest suite), pyproject.toml, a README.md, and an MCP client config.json — a complete project, not a snippet. Run it with:
cd weather-server
uv run server.py # start the server (streamable-http)
uv run pytest -v # run the generated tests
mcpforge validate . # re-run the full validation suite anytime
The snippet above is an illustrative toy ("weather") for the docs. Real generations match your description — see
examples/for live generated servers (todo, file reader, database query, Slack notifier, TypeScript).
Related MCP server: MCP Server Generator
Build, then audit — the MCP toolkit
mcpforge has a sibling: mcp-audit (mcp-audits on PyPI). They're two halves of one workflow — forge a server, then audit what your agents can actually touch before you trust it.
Stage | Tool | What it does |
Build |
| Generate a complete, tested MCP server from one sentence. |
Audit |
| Scan every MCP server wired into your machine and risk-score what each one can reach. |
# build
mcpforge generate "A weather server that returns today's forecast for a city" -o weather-server
# audit everything your agents can reach (read-only, no install needed)
uvx --from mcp-audits mcp-audit scan --ssrf-checkmcp-audit is read-only by default — it never edits a config and reports env-var key names only, never values. Build with confidence, then verify your blast radius.
Registry-ready metadata lives in server.json with the MCP Registry name
io.github.saagpatel/mcpforge and PyPI package fastmcp-builder. Treat that metadata as
discovery/provenance context, not as proof that generated servers are safe to run without review.
Use as an MCP server
mcpforge is itself an MCP server: point an MCP client (Claude Code, Claude Desktop, Cursor) at it and your agent can forge, validate, and inspect MCP servers inside a conversation. It runs locally over stdio (it writes files into your workspace and calls your model provider on your own key), so it is not offered as a hosted remote.
uvx fastmcp-builderAdd it to a client config (Claude Code shown). generate, update, and plan call the model provider, so set the key in the server env:
{
"mcpServers": {
"mcpforge": {
"command": "uvx",
"args": ["fastmcp-builder"],
"env": { "ANTHROPIC_API_KEY": "<your-key>", "MCPFORGE_WORKSPACE": "/path/to/workspace" }
}
}
}Workspace paths are resolved against MCPFORGE_WORKSPACE and confined to it. Note that generate and update write files and incur model-provider cost (roughly $0.05 to $0.30 per call on your key).
Tool | What it does | Writes | Cost | Key args |
| Generate a complete, tested FastMCP 3.x server from a description | yes (workspace) | API call |
|
| Apply a natural-language change to an existing generated server | yes (workspace) | API call |
|
| Extract the structured server plan without generating code | no | API call |
|
| Run syntax, lint, import, and pytest checks on a generated server | no (executes tests) | none |
|
| Summarize a generated server without executing it | no | none |
|
| Check local prerequisites and provider readiness | no | none |
|
| List mcpforge-generated servers in a workspace | no | none |
|
Features
Plain-English generation — describe your server in natural language; Claude writes the implementation
Complete project scaffold — tools, Pydantic input models, error handling,
pyproject.toml, and a pytest suite generated togetherFastMCP 3.x native — output uses modern FastMCP decorators and transport configuration, not raw MCP protocol boilerplate
Validate before running —
mcpforge validateruns syntax, security, lint, import, and pytest checks against generated serversIterate safely —
mcpforge updatemodifies an existing generated server and backs up changed files before writingDiscover generated servers —
mcpforge listfinds mcpforge-generated projects in a workspaceInspect and diagnose —
mcpforge inspectsummarizes generated server shape, whilemcpforge doctorchecks local readinessMachine-readable output — status-like commands expose
--jsonfor agent workflowsOpenAPI curation controls — include/exclude tags, operation allowlists, and operation limits keep generated integrations focused
Scaffold without an LLM —
mcpforge initcreates a minimal FastMCP server skeleton for local iterationMCP server mode —
mcpforge-serverexposes generation, planning, validation, inspection, doctor, and discovery tools so AI assistants can build safely
Pagination contracts and failure semantics
The pagination contract docs describe adapter behavior,
protocol-level list pagination, and observed traversal outcomes. Pagination
incompleteness follows the shared failure contract.
Run mcpforge contracts fixtures to compare all pagination and upstream failure
fixtures across the supported runtimes. Regenerate or check the examples in the
docs with mcpforge contracts pagination-docs [--path DIR] [--check] and
mcpforge contracts failure-docs [--path FILE] [--check]. Paths default to
docs/pagination and docs/FAILURE-SEMANTICS.md under the current directory.
Installable example servers for each pattern (cursor,
offset,
page-token) demonstrate pagination over
stdio. Generate your own with mcpforge contracts pagination-example PATTERN --output DIR.
More commands
The PyPI distribution is fastmcp-builder; the installed commands are mcpforge and mcpforge-server. Beyond generate:
# See it work with no API key — generate a weather server from a built-in recording
mcpforge demo
# Generate a new MCP server
mcpforge generate "A todo list manager with create, read, update, and delete operations"
# Validate an existing generated server
mcpforge validate ./my-server
# Modify an existing generated server
mcpforge update ./my-server "Add a tool to export todos as CSV"
# Find generated servers in the current workspace
mcpforge list . --recursive
# Inspect a generated server without executing it
mcpforge inspect ./my-server
# Check local prerequisites and provider readiness
mcpforge doctorUseful generation flags:
--dry-rundisplays the structured plan without writing files.--no-executewrites files but skips dependency installation and generated-code execution. Python still reports static syntax, security, and lint results; imports and generated tests do not run. TypeScript also skips type checking and generated tests, and its MCP response reportsvalidation_mode: "write_only"andtests_status: "not_run". Provider-backed planning and code generation may still make API calls. The legacytests_okflag alone does not prove tests ran.--stricttreats Python lint errors as hard validation failures; TypeScript has no lint stage.--from-openapi FILEgenerates from an OpenAPI 3.x spec.--openapi-include-tag TAG,--openapi-exclude-tag TAG,--openapi-operation ID, and--openapi-limit Ncurate OpenAPI conversion.--language python|typescriptchooses the target server language.--auth-profile none|api-key|jwtadds optional Python auth profile metadata and env docs.--middleware-profile logging|timing|rate-limitadds optional Python middleware profiles; repeat it to combine profiles.--provider anthropic|openai|openrouterselects the generation provider.openrouteris the "bring any model" path: setOPENROUTER_API_KEYand pick any OpenRouter model with--model(e.g.--model anthropic/claude-opus-4.8), including free and low-cost ones. Generation quality and structured-output support vary by model — the recommended models are Claude Opus 4.8 (xHigh) and/or GPT 5.5 (High/Extra High). Theopenaipackage is a default dependency (included in all installs) because it backs both--provider openaiand--provider openrouter; setMCPFORGE_ENABLE_OPENAI_PROVIDER=1to enable the direct OpenAI provider for use withOPENAI_API_KEY.
Useful status flags:
mcpforge list --jsonmcpforge inspect PATH --jsonmcpforge validate PATH --jsonmcpforge doctor --jsonmcpforge version --json
mcpforge doctor --json always prints the complete JSON report and exits 0 when
the report's ok is true, or 1 when it is false, matching ordinary doctor.
For Cloud development, use the portable MCP Forge Cloud workflow skill. It covers prepared startup and credential-free checks, continuing an authorized existing PR, and the tested GitHub connector fallback when configured Git transport is blocked, with remote history and tested contents verified before delivery.
Tech Stack
Layer | Technology |
Language | Python 3.12+ |
Generation | Anthropic Claude via |
MCP framework | FastMCP 3.x |
CLI | Click 8 |
Templates | Jinja2 |
Validation | Pydantic v2 |
Output | Rich |
Development setup
The repository pins Python 3.12.15 in .python-version and requires uv 0.13.0 or later. Set up the locked environment and run the full local check with:
make setup
make checkmake check includes validation of examples/todo-server; on macOS it uses the available sandbox-exec boundary. CI disables that wrapper for the example-validation command because GitHub-hosted runners do not provide it.
Architecture
The generate command sends the user's description to Claude with a structured prompt that includes FastMCP 3.x idioms and a tool-schema contract. Claude returns a JSON plan (tool names, signatures, and descriptions) that mcpforge validates against a Pydantic model before rendering through Jinja2 templates into a complete project directory. The generated project is then validated with syntax checks, security scanning, ruff linting, import checks, and pytest execution. The update command reads an existing generated server, asks Claude for a targeted modification, writes backups for changed files, and validates the result.
Status
Stack
The current package version is 0.3.4, published to PyPI as fastmcp-builder. It adds a fastmcp-builder console-script alias and corrects the registry metadata. Version 0.3.3 added mcpforge demo, the OpenRouter provider, and MCP Registry metadata. The project targets Python 3.12+ and FastMCP 3.x. The repository toolchain pins Python 3.12.15 and requires uv 0.13.0 or later.
Known risks
Generated code runs during ordinary validation. macOS uses
sandbox-execwhen available; non-macOS validation runs without that sandbox. Review generated code before use.Python
--no-executeperforms static syntax, security, and lint checks only; imports and generated tests do not run. Static results are not proof of runtime behavior.The update command currently handles Python servers. TypeScript validation is narrower than the Python validation pipeline and does not use the Python lint or security stages.
Provider compatibility and deployment readiness depend on the selected provider and environment. See the provider matrix.
Next steps
Use CHANGELOG.md for release history and the provider matrix for hosted-provider readiness before planning release work.
See CHANGELOG.md for the full version history.
License
MIT
Available Tools
7 toolsdoctorB
Check local mcpforge prerequisites and provider readiness.
Inputs: workspace_path. Returns: object
generateB
Generate a complete FastMCP 3.x server from a plain-English description.
Returns a dict with keys: path, plan (dict), valid (bool), tests_run (int).
Inputs: description (required), model, strict, dry_run, +10 more. Returns: object
inspectC
Inspect a generated server without executing it.
Inputs: server_path (required). Returns: object
list_generated_serversB
List generated mcpforge servers in a workspace.
Inputs: recursive, workspace_path. Returns: object
planA
Extract the structured server plan without generating code.
Returns a dict with keys: name, slug, description, tools (list), transport.
Inputs: description (required), model, provider, transport. Returns: object
updateB
Apply a natural-language modification request to an existing MCP server.
Returns a dict with keys: path, valid (bool), tests_run (int).
Inputs: request (required), server_path (required), model, provider. Returns: object
validateB
Validate an existing MCP server. Returns detailed validation results.
Inputs: server_path (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools target distinct actions: generate, update, validate, plan, inspect, doctor, and list are generally clear. However, plan and generate overlap somewhat since generate also produces a plan, and inspect vs. validate could be confused without closer reading.
Tool names are mostly simple imperative verbs like generate, update, validate, and inspect, which creates a readable pattern. The one outlier is list_generated_servers, but it is still understandable and not disruptive.
Seven tools is well within the ideal range for a code-generation focused server. Each tool contributes a meaningful step in the workflow without unnecessary redundancy.
The toolset covers the core creation, update, validation, and inspection lifecycle for generated servers. The main gap is the lack of a delete or remove tool for cleaning up generated servers.
Maintenance
Related MCP Connectors
MCP server for generating rough-draft project plans from natural-language prompts.
Create guides as MCP servers to instruct coding agents to use your software (library, API, etc).
Primarily to be used as a template repository for developing MCP servers with FastMCP in Python, P…
Build your own tools from chat: design, test and host them on a shareable MCP server URL.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceGenerates production-ready MCP servers from natural language, OpenAPI specs, database schemas, GraphQL schemas, or ontologies.49 npm1MIT
- AlicenseAqualityDmaintenanceGenerates production-ready MCP servers with dual-mode (MCP + CLI) architecture, tests, and documentation. Includes progressive disclosure tools for AI agents and best practices guidance.7Apache 2.0
- AlicenseNot gradedqualityDmaintenanceGenerates and serves an MCP server from a natural language prompt, without requiring SDK knowledge or boilerplate code.11 npm1Apache 2.0
- FlicenseNot gradedqualityDmaintenanceAutomatically generates, validates, and deploys remote MCP servers from natural language descriptions, with a web dashboard for management.-