mcpforge

mcpforge

[PyPI] [Python] [CI] [License: MIT]

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

[mcpforge demo: one command to a tested, validated MCP server]

You need Python 3.12+, uv, and an Anthropic API key.

uv tool install fastmcp-builder      # or: pip install fastmcp-builderexport ANTHROPIC_API_KEY="your_anthropic_api_key"
mcpforge generate "A weather server that returns today's forecast for a city" -o weather-server

No key yet? Try the demo. mcpforge demo runs 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:

bash

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 generate makes 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, and init — 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.toolasync 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-serveruv run server.py            # start the server (streamable-http)uv run pytest -v            # run the generated testsmcpforge validate .         # re-run the full validation suite anytime

[Generated server: tests pass, then it runs]

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).

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.

# buildmcpforge 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-check

mcp-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-builder

Add 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).

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 together
• FastMCP 3.x native — output uses modern FastMCP decorators and transport configuration, not raw MCP protocol boilerplate
• Validate before running — mcpforge validate runs syntax, security, lint, import, and pytest checks against generated servers
• Iterate safely — mcpforge update modifies an existing generated server and backs up changed files before writing
• Discover generated servers — mcpforge list finds mcpforge-generated projects in a workspace
• Inspect and diagnose — mcpforge inspect summarizes generated server shape, while mcpforge doctor checks local readiness
• Machine-readable output — status-like commands expose --json for agent workflows
• OpenAPI curation controls — include/exclude tags, operation allowlists, and operation limits keep generated integrations focused
• Scaffold without an LLM — mcpforge init creates a minimal FastMCP server skeleton for local iteration
• MCP server mode — mcpforge-server exposes generation, planning, validation, inspection, doctor, and discovery tools so AI assistants can build safely

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 recordingmcpforge demo
# Generate a new MCP servermcpforge generate "A todo list manager with create, read, update, and delete operations"
# Validate an existing generated servermcpforge validate ./my-server
# Modify an existing generated servermcpforge update ./my-server "Add a tool to export todos as CSV"
# Find generated servers in the current workspacemcpforge list . --recursive
# Inspect a generated server without executing itmcpforge inspect ./my-server
# Check local prerequisites and provider readinessmcpforge doctor

Useful generation flags:

• --dry-run displays the structured plan without writing files.
• --no-execute writes 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 reports validation_mode: "write_only" and tests_status: "not_run". Provider-backed planning and code generation may still make API calls. The legacy tests_ok flag alone does not prove tests ran.
• --strict treats Python lint errors as hard validation failures; TypeScript has no lint stage.
• --from-openapi FILE generates from an OpenAPI 3.x spec.
• --openapi-include-tag TAG, --openapi-exclude-tag TAG, --openapi-operation ID, and --openapi-limit N curate OpenAPI conversion.
• --language python|typescript chooses the target server language.
• --auth-profile none|api-key|jwt adds optional Python auth profile metadata and env docs.
• --middleware-profile logging|timing|rate-limit adds optional Python middleware profiles; repeat it to combine profiles.
• --provider anthropic|openai|openrouter selects the generation provider. openrouter is the "bring any model" path: set OPENROUTER_API_KEY and 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). The openai package is a default dependency (included in all installs) because it backs both --provider openai and --provider openrouter; set MCPFORGE_ENABLE_OPENAI_PROVIDER=1 to enable the direct OpenAI provider for use with OPENAI_API_KEY.

Useful status flags:

• mcpforge list --json
• mcpforge inspect PATH --json
• mcpforge validate PATH --json
• mcpforge doctor --json
• mcpforge 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

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 setupmake check

make 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-exec when available; non-macOS validation runs without that sandbox. Review generated code before use.
• Python --no-execute performs 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