{"id":51224824,"url":"https://github.com/saagpatel/mcpforge","last_synced_at":"2026-06-28T10:03:14.077Z","repository":{"id":347875888,"uuid":"1195315318","full_name":"saagpatel/mcpforge","owner":"saagpatel","description":"Generate production-ready FastMCP 3.x MCP servers from plain-English descriptions","archived":false,"fork":false,"pushed_at":"2026-06-19T05:23:13.000Z","size":666,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-19T07:11:28.089Z","etag":null,"topics":["ai-tools","anthropic","cli","code-generation","developer-tools","fastmcp","mcp","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/fastmcp-builder/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/saagpatel.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP-v0.3.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-29T14:19:09.000Z","updated_at":"2026-06-19T05:23:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/saagpatel/mcpforge","commit_stats":null,"previous_names":["saagpatel/mcpforge"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/saagpatel/mcpforge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saagpatel%2Fmcpforge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saagpatel%2Fmcpforge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saagpatel%2Fmcpforge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saagpatel%2Fmcpforge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/saagpatel","download_url":"https://codeload.github.com/saagpatel/mcpforge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saagpatel%2Fmcpforge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34884278,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","anthropic","cli","code-generation","developer-tools","fastmcp","mcp","python"],"created_at":"2026-06-28T10:03:13.525Z","updated_at":"2026-06-28T10:03:14.070Z","avatar_url":"https://github.com/saagpatel.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mcpforge\n\n\u003c!-- mcp-name: io.github.saagpatel/mcpforge --\u003e\n\n[![PyPI](https://img.shields.io/pypi/v/fastmcp-builder?style=flat-square\u0026logo=pypi\u0026logoColor=white\u0026label=PyPI)](https://pypi.org/project/fastmcp-builder/)\n[![Python](https://img.shields.io/pypi/pyversions/fastmcp-builder?style=flat-square\u0026logo=python\u0026logoColor=white)](https://pypi.org/project/fastmcp-builder/)\n[![CI](https://img.shields.io/github/actions/workflow/status/saagpatel/mcpforge/ci.yml?style=flat-square\u0026logo=githubactions\u0026logoColor=white\u0026label=CI)](https://github.com/saagpatel/mcpforge/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/saagpatel/mcpforge/blob/main/LICENSE)\n\n\u003e ### One English sentence in. A tested, spec-free FastMCP 3.x server out.\n\n**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.\n\n## ⚡ 60-second start\n\n![mcpforge demo: one command to a tested, validated MCP server](https://raw.githubusercontent.com/saagpatel/mcpforge/main/docs/assets/hero.gif)\n\nYou need Python 3.12+, [`uv`](https://docs.astral.sh/uv/), and an Anthropic API key.\n\n```bash\nuv tool install fastmcp-builder      # or: pip install fastmcp-builder\nexport ANTHROPIC_API_KEY=\"your_anthropic_api_key\"\n\nmcpforge generate \"A weather server that returns today's forecast for a city\" -o weather-server\n```\n\n\u003e **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:\n\u003e\n\u003e ```bash\n\u003e uvx --from fastmcp-builder mcpforge demo\n\u003e ```\n\n\u003e **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.\n\nThat'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:\n\n```python\n# weather-server/server.py  (excerpt)\n\"\"\"Weather forecast MCP server.\"\"\"\n\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"Weather\")\n\n# Illustrative lookup — describe a real source and mcpforge wires the call for you.\n_FORECASTS: dict[str, dict] = {\n    \"san francisco\": {\"high_c\": 18, \"low_c\": 12, \"summary\": \"Foggy\"},\n    \"denver\": {\"high_c\": 24, \"low_c\": 9, \"summary\": \"Clear\"},\n}\n\n\n@mcp.tool\nasync def get_forecast(city: str) -\u003e dict:\n    \"\"\"Return today's forecast for a city.\"\"\"\n    key = city.strip().lower()\n    if key not in _FORECASTS:\n        raise ValueError(f\"No forecast available for {city!r}\")\n    return {\"city\": city, **_FORECASTS[key]}\n\n\nif __name__ == \"__main__\":\n    mcp.run(transport=\"streamable-http\")\n```\n\nEvery 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:\n\n```bash\ncd weather-server\nuv run server.py            # start the server (streamable-http)\nuv run pytest -v            # run the generated tests\nmcpforge validate .         # re-run the full validation suite anytime\n```\n\n![Generated server: tests pass, then it runs](https://raw.githubusercontent.com/saagpatel/mcpforge/main/docs/assets/run-and-test.gif)\n\n\u003e The snippet above is an illustrative toy (\"weather\") for the docs. Real generations match your description — see [`examples/`](https://github.com/saagpatel/mcpforge/tree/main/examples) for live generated servers (todo, file reader, database query, Slack notifier, TypeScript).\n\n## Build, then audit — the MCP toolkit\n\nmcpforge has a sibling: **[mcp-audit](https://github.com/saagpatel/MCPAudit)** (`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.\n\n| Stage | Tool | What it does |\n|-------|------|--------------|\n| **Build** | `mcpforge` | Generate a complete, tested MCP server from one sentence. |\n| **Audit** | `mcp-audit` | Scan every MCP server wired into your machine and risk-score what each one can reach. |\n\n```bash\n# build\nmcpforge generate \"A weather server that returns today's forecast for a city\" -o weather-server\n\n# audit everything your agents can reach (read-only, no install needed)\nuvx --from mcp-audits mcp-audit scan --ssrf-check\n```\n\n\u003c!-- Record the build+audit GIF (`vhs docs/assets/build-then-audit.tape`), then uncomment the line below: --\u003e\n\u003c!-- ![Forge a server, then audit your MCP surface](https://raw.githubusercontent.com/saagpatel/mcpforge/main/docs/assets/build-then-audit.gif) --\u003e\n\n`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.\n\nRegistry-ready metadata lives in [`server.json`](server.json) with the MCP Registry name\n`io.github.saagpatel/mcpforge` and PyPI package `fastmcp-builder`. Treat that metadata as\ndiscovery/provenance context, not as proof that generated servers are safe to run without review.\n\n## Use as an MCP server\n\nmcpforge 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.\n\n```bash\nuvx fastmcp-builder\n```\n\nAdd it to a client config (Claude Code shown). `generate`, `update`, and `plan` call the model provider, so set the key in the server env:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcpforge\": {\n      \"command\": \"uvx\",\n      \"args\": [\"fastmcp-builder\"],\n      \"env\": { \"ANTHROPIC_API_KEY\": \"\u003cyour-key\u003e\", \"MCPFORGE_WORKSPACE\": \"/path/to/workspace\" }\n    }\n  }\n}\n```\n\nWorkspace 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).\n\n| Tool | What it does | Writes | Cost | Key args |\n|---|---|---|---|---|\n| `generate` | Generate a complete, tested FastMCP 3.x server from a description | yes (workspace) | API call | `description`, `language`, `transport`, `output_path`, `dry_run` |\n| `update` | Apply a natural-language change to an existing generated server | yes (workspace) | API call | `server_path`, `request` |\n| `plan` | Extract the structured server plan without generating code | no | API call | `description`, `transport` |\n| `validate` | Run syntax, lint, import, and pytest checks on a generated server | no (executes tests) | none | `server_path` |\n| `inspect` | Summarize a generated server without executing it | no | none | `server_path` |\n| `doctor` | Check local prerequisites and provider readiness | no | none | `workspace_path` |\n| `list_generated_servers` | List mcpforge-generated servers in a workspace | no | none | `workspace_path`, `recursive` |\n\n## Features\n\n- **Plain-English generation** — describe your server in natural language; Claude writes the implementation\n- **Complete project scaffold** — tools, Pydantic input models, error handling, `pyproject.toml`, and a pytest suite generated together\n- **FastMCP 3.x native** — output uses modern FastMCP decorators and transport configuration, not raw MCP protocol boilerplate\n- **Validate before running** — `mcpforge validate` runs syntax, security, lint, import, and pytest checks against generated servers\n- **Iterate safely** — `mcpforge update` modifies an existing generated server and backs up changed files before writing\n- **Discover generated servers** — `mcpforge list` finds mcpforge-generated projects in a workspace\n- **Inspect and diagnose** — `mcpforge inspect` summarizes generated server shape, while `mcpforge doctor` checks local readiness\n- **Machine-readable output** — status-like commands expose `--json` for agent workflows\n- **OpenAPI curation controls** — include/exclude tags, operation allowlists, and operation limits keep generated integrations focused\n- **Scaffold without an LLM** — `mcpforge init` creates a minimal FastMCP server skeleton for local iteration\n- **MCP server mode** — `mcpforge-server` exposes generation, planning, validation, inspection, doctor, and discovery tools so AI assistants can build safely\n\n## More commands\n\nThe PyPI distribution is `fastmcp-builder`; the installed commands are `mcpforge` and `mcpforge-server`. Beyond `generate`:\n\n```bash\n# See it work with no API key — generate a weather server from a built-in recording\nmcpforge demo\n\n# Generate a new MCP server\nmcpforge generate \"A todo list manager with create, read, update, and delete operations\"\n\n# Validate an existing generated server\nmcpforge validate ./my-server\n\n# Modify an existing generated server\nmcpforge update ./my-server \"Add a tool to export todos as CSV\"\n\n# Find generated servers in the current workspace\nmcpforge list . --recursive\n\n# Inspect a generated server without executing it\nmcpforge inspect ./my-server\n\n# Check local prerequisites and provider readiness\nmcpforge doctor\n```\n\nUseful generation flags:\n- `--dry-run` displays the structured plan without writing files.\n- `--no-execute` writes files but skips import and test execution.\n- `--strict` treats lint errors as hard validation failures.\n- `--from-openapi FILE` generates from an OpenAPI 3.x spec.\n- `--openapi-include-tag TAG`, `--openapi-exclude-tag TAG`, `--openapi-operation ID`, and `--openapi-limit N` curate OpenAPI conversion.\n- `--language python|typescript` chooses the target server language.\n- `--auth-profile none|api-key|jwt` adds optional Python auth profile metadata and env docs.\n- `--middleware-profile logging|timing|rate-limit` adds optional Python middleware profiles; repeat it to combine profiles.\n- `--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`.\n\nUseful status flags:\n- `mcpforge list --json`\n- `mcpforge inspect PATH --json`\n- `mcpforge validate PATH --json`\n- `mcpforge doctor --json`\n- `mcpforge version --json`\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|------------|\n| Language | Python 3.12+ |\n| Generation | Anthropic Claude via `anthropic` SDK; OpenAI and OpenRouter via `openai` SDK (included by default) |\n| MCP framework | FastMCP 3.x |\n| CLI | Click 8 |\n| Templates | Jinja2 |\n| Validation | Pydantic v2 |\n| Output | Rich |\n\n## Architecture\n\nThe `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.\n\n## Current Status — v0.3.4\n\nmcpforge is published to PyPI as `fastmcp-builder`. v0.3.4 adds a `fastmcp-builder`\nconsole-script alias so the MCP server launches via `uvx fastmcp-builder` (matching the\nMCP Registry's `uvx \u003cpackage\u003e` launch model) and corrects the registry metadata. v0.3.3\nadded the `mcpforge demo` command (try the full generate pipeline with no API key, no\ncost), an OpenRouter provider (`--provider openrouter`), and official MCP Registry\nmetadata. The `generate`, `update`, `validate`, `inspect`, `doctor`, and `demo` commands\nwork against FastMCP 3.4.2+.\n\nSee [CHANGELOG.md](CHANGELOG.md) for the full version history.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaagpatel%2Fmcpforge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaagpatel%2Fmcpforge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaagpatel%2Fmcpforge/lists"}