MCP-Generator
Also available in: Português (Versão em Português)
Generate MCP servers from OpenAPI specs.
Status:
@christopher_dondici/mcp-gen2.3.7 is the latest published version on npm; 2.4.0 is prepared (publication pending). See (PT-BR).
接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y @christopher_dondici/[email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
claude mcp add christopher_dondici-mcp-gen -- npx -y @christopher_dondici/mcp-gen@2.5.0在終端機中執行。
{ "mcpServers": { "christopher_dondici-mcp-gen": { "command": "npx", "args": [ "-y", "@christopher_dondici/[email protected]" ] } }}claude_desktop_config.json
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
Also available in: Português (Versão em Português)
Generate MCP servers from OpenAPI specs.
Status:
@christopher_dondici/mcp-gen2.3.7 is the latest published version on npm; 2.4.0 is prepared (publication pending). See (PT-BR).
OpenAPI → MCP Server generator CLI
mcp-gen turns an OpenAPI v3 or Swagger 2.0 spec into an MCP server in TypeScript, Python, or Go. It maps each route to a tool, generates typed models (including enums, oneOf/anyOf), and keeps custom code when you regenerate.
(Minor release — no breaking changes. Prepared, publication pending. Includes the unreleased 2.3.8 content.)
oneOf/anyOf variants become synthetic union members with expanded properties instead of warnings; discriminator stays advisory-only.allOf members expand recursively; requestBody.$ref to schemas/* resolves as the body param (to parameters/* warns instead of dropping silently).$ref parameters via components.parameters are resolved; unresolvable ones warn; pnpm-lock.yaml and bun.lock/bun.lockb are skipped by the credential scan.proxy-addr → 2.0.8, handlebars → 4.7.10 (prod audit clean); streamed remote reads with 50MB cap; CI on Node 22 with pinned ubuntu-24.04; 4 Wave 1 lows.npm audit --omit=dev clean.(Minor release — no breaking changes.)
watch retries transient fetch failures instead of dropping the polling cycle: network errors and 408/425/429/500/502/503/504 responses are retried with exponential backoff, while other 4xx responses fail immediately.--retries <n> (default 2) and --retry-delay <ms> (default 500) flags control the retry budget and the base backoff, which doubles on each attempt. --retries 0 keeps the previous single-attempt behaviour.(Patch release — no breaking changes.)
operationId when present, with fallback to method_path.allOf with $ref merges referenced properties; requestBody resolves via components.requestBodies; trace is a supported method.security --json prints pure JSON on stdout for CI parsing; --plugin accepts a directory or a module file.watch validates the URL, enforces a 30s timeout and content checks, and compares by SHA-256 hash.security-lint has fewer false positives (anchored base64 regex, lockfiles skipped, all specs scanned).(Patch release — no breaking changes.)
watch --interval now fails with an explicit error instead of silently falling back to 30s.init accepts --timeout <ms> and --max-bytes <bytes> for the registry download (defaults 30s / 50MB) with explicit validation.body params, file outside formData, non-csv collectionFormat).discriminator now warns per schema (advisory only, nothing breaks).LINT-TODO-IN-GENERATED no longer fires inside examples/.ubuntu-latest + windows-latest.(Patch release — no breaking changes.)
METHOD path now matches case-insensitively (get /pets = GET /pets).Filters matched 0 of N tools warning suggesting --dry-run.handler not implemented); untouched stubs are no longer preserved as custom.application/json is absent (covers multipart/form-data and urlencoded from Swagger 2.0 formData conversion).npm audit --omit=dev clean.(Patch release — no breaking changes.)
ip-address 10.4.0 → 10.7.2 through the SDK transitive chain (express-rate-limit ^10.2.0), so npm audit --omit=dev is clean again.tests/scaffold-lockfile.test.ts guard: scaffold package.json.hbs ranges against the package-lock.json.hbs snapshot, plus an ip-address floor above 10.5.0 in both project and scaffold lockfiles.js-yaml finding stays documented in SECURITY.md, with no broad Jest upgrade on the 2.3.x line.npm audit --omit=dev clean.(Patch release — no breaking changes.)
--env-file paths now fail with an explicit error instead of being silently ignored.init flow shows Go next steps (go mod tidy && go run .) instead of suggesting pip install.dist is cleaned before every build, so stale artifacts can't leak into builds or tarballs.npm audit --omit=dev clean.(Patch release — no breaking changes.)
js-yaml and openapi-types are now direct dependencies instead of transitive ones; YAML spec scanning in security-lint uses a typed import.fetch./** path globs also match the base path, so /pets/** includes /pets.<generated:handlers:name> guards alongside the legacy @@mcp-gen markers.npm run test:generated:go): the Petstore Go scaffold runs go mod tidy + go build, also gated in CI with Go 1.22.npm audit --omit=dev clean.(Patch release — no breaking changes.)
package-lock.json, so their CI and Docker npm ci commands work from a fresh checkout.--force now takes precedence when combined with --incremental, discarding preserved handlers as documented.watch --once returns exit code 1 on fetch, parse, or generation failures and uses Commander's async action flow.npm pack --dry-run.(Fase 2 — anchor: unlocks the registry, no breaking changes.)
host/basePath/schemes → servers, definitions → components.schemas, body/formData → requestBody, securityDefinitions → securitySchemes). validate + generate accept v2 files (see examples/swagger-v2-petstore.json).slack, kubernetes, digitalocean are back (v2, converted on the fly); only azure stays removed (it was a types fragment, not a full spec).examples/large-scale.json (180 ops, 10 tags) proves 180 → 10 tools with --group-by tag (also 10 with path-prefix). See Benchmark.(Fase 1 — solid base, no breaking changes.)
generate --dry-run lists tools/models/groups/files without writing anything; --json prints a machine-readable summary (Codex-friendly, no chalk noise).watch accepts the same filter/group flags as generate, and the interactive mode asks for filters and grouping. watch --once exits after the first generation on file inputs too.validate (and generate) warn per affected schema when allOf $refs are skipped or inline oneOf/anyOf variants are dropped (partial support is no longer silent).MCP_GEN_ALLOW_PLUGINS documented in Plugins.(Fase 0, PR #4 — P0 fixes on top of 2.1.4.)
queryNames + URLSearchParams); get_pets({ limit: 5 }) calls /pets?limit=5._build_query / _build_headers, kwargs["params"]) in --http mode, including grouped tools.--http mode wired to the real APIClient (__client.do(...), q.Encode(), PathEscape), no more not yet wired stubs.stripe, github, openai, petstore, twilio, shopify); removed keys fail with guidance and unknown keys list Known keys; v2 specs fail with Only OpenAPI v3.(The v2.1.3 tag was superseded before reaching npm; everything below shipped in 2.1.4, plus a fix for the generated auth middleware on specs without securitySchemes.)
--path-prefix "/users/**", --include-paths, --exclude-paths; inline --operation-allowlist op1,op2 (file still supported).--group-by tag | path-prefix: one logical tool per tag or path segment, routing internally by action (operation name + method).<generated:handlers> regions plus per-tool @@mcp-gen markers, 3-way merge on --incremental, --force to overwrite.src/auth.ts, auth.py, auth.go) generated from securitySchemes, and handlers.custom.* files that are never overwritten without --force.With Git, Node.js 20+ and npm 9+ installed, run:
git clone https://github.com/ChristopherDond/MCP-Generator.git
cd MCP-Generator
npm ci
npm run build
node dist/cli/index.js --version
Generate a server from a local spec:
node dist/cli/index.js generate -i examples/petstore.yaml -l typescript -o ./my-server
Validate a spec without generating files:
node dist/cli/index.js validate -i examples/petstore.yaml
Run these commands from the repository root on main. The build and packaging fixes are part of 2.1.2. Generation writes a scaffold; it does not install dependencies, build, or start the generated server.
Run the interactive CLI if you prefer prompts:
npm run dev
sequenceDiagram
participant User
participant CLI
participant Parser
participant Generator
participant Output
User->>CLI: mcp-gen generate --input api.yaml --lang go
CLI->>Parser: validate and parse OpenAPI v3 / Swagger 2.0 (JSON or YAML)
Parser->>Generator: internal AST (tools, models, examples)
Generator->>Output: render Handlebars templates
Output-->>User: TypeScript, Python, or Go MCP server project
Each route becomes an MCP tool with:
--http) that calls the actual APIInstall the latest release with npm install -g @christopher_dondici/[email protected]. To work from source, use the build in Quick start.
Throughout this README, mcp-gen is shorthand for node dist/cli/index.js from the repository root. For example, mcp-gen validate -i examples/petstore.yaml means node dist/cli/index.js validate -i examples/petstore.yaml.
Optionally, run npm link from the repository root after building to make the mcp-gen command point to your local checkout. This changes npm's global links; it does not download a published @christopher_dondici/mcp-gen package. The npm package name changed because mcp-gen was rejected for similarity to mcpgen; the command remains mcp-gen.
To install a locally produced tarball without publishing:
npm install ./christopher_dondici-mcp-gen-2.3.7.tgz
./node_modules/.bin/mcp-gen --version
./node_modules/.bin/mcp-gen validate -i node_modules/@christopher_dondici/mcp-gen/examples/petstore.yaml
mcp-gen generate or mcp-gen g creates a server from a spec.mcp-gen validate or mcp-gen v checks a spec with detailed warnings (name collisions, missing examples, unsupported schemas).mcp-gen init downloads a known public spec and can generate a project.mcp-gen watch watches a file or URL and regenerates on changes.mcp-gen generate -i ./api/openapi.yaml -l typescript -o ./my-server
mcp-gen generate -i ./api/openapi.yaml -l python -o ./my-server
mcp-gen generate -i ./api/openapi.yaml -l go -o ./my-server
Useful flags:
--force, -f overwrites existing files, ignoring preserved handlers and custom files (skips 3-way merge). It wins when combined with --incremental.--incremental keeps code between @@mcp-gen:start and @@mcp-gen:end (also <generated:handlers:name>). Uses 3-way merge: base stub vs your custom code vs new template.--http generates handlers that call the real API over HTTP instead of returning example stubs.--env-file <path> embeds TOKEN/BASE_URL from a .env-style file into the generated client.--name <name> sets the server name.--server-version <version> sets the server version.--plugin <path> loads a plugin module or folder (can be repeated).--include-tags <a,b> only includes tools with one of these tags.--exclude-tags <a,b> excludes tools with these tags.--path-prefix <glob> only includes paths matching a prefix or glob (/users, /users/**, /pets/*).--include-paths <globs> comma-separated path globs to include.--exclude-paths <globs> comma-separated path globs to exclude.--operation-allowlist <ops> comma-separated operationId, tool name, or METHOD /path list, or a path to an allowlist file (JSON array or line/comma separated).--group-by <mode> aggregates to one logical tool per group: tag or path-prefix. Each group routes by action (operation name) internally.--dry-run lists tools/models/groups/files that would be generated without writing anything.--json prints the generation summary as machine-readable JSON (pairs with --dry-run for scripting).mcp-gen generate -i api.yaml -o ./out --include-tags pets,orders
mcp-gen generate -i api.yaml -o ./out --exclude-tags admin
mcp-gen generate -i api.yaml -o ./out --path-prefix "/users/**"
mcp-gen generate -i api.yaml -o ./out --include-paths "/users/**,/orders/*" --exclude-paths "/users/internal/*"
mcp-gen generate -i api.yaml -o ./out --operation-allowlist listPets,createPet
mcp-gen generate -i api.yaml -o ./out --operation-allowlist ./allow.json
mcp-gen generate -i api.yaml -o ./out --include-tags pets --group-by tag
--group-by tag emits one tool per tag (plus untagged), e.g. 200 operations across 8 tags become ~8 tools. --group-by path-prefix emits one tool per first path segment (/users/** becomes users_group). Each grouped tool takes a required action enum (member operation names) and routes internally by METHOD + path. Member params are unioned as optional.
Measured on examples/large-scale.json (180 ops across 10 tags, 2 models):
180 → 10 tools — grouping cuts the surface by 18x on this fixture. Covered by tests/scale.test.ts.
Tool names come from METHOD + path (GET /pets/{id} becomes get_pets_petid). operationId is stored for allowlist matching. On collision the generator suffixes with the method first, then with a short path hash, instead of emitting duplicate tools.
Generated projects include a separate auth layer built from securitySchemes:
src/auth.tsauth.pyauth.goPut business logic in guards; keep auth and schema validation in the middleware so you do not need a guard for auth.
Generated handlers are wrapped in two markers:
// <generated:handlers>
// @@mcp-gen:start:get_pets
// ... your code here ...
// @@mcp-gen:end:get_pets
// </generated:handlers>
Rules:
@@mcp-gen:start:<tool> and @@mcp-gen:end:<tool> (or <generated:handlers:<tool>>). That body is preserved on regen.src/handlers.custom.ts (TS), handlers_custom.py (Python), or handlers_custom.go (Go). That file is created once and never overwritten unless you pass --force.generate --incremental. The generator does a 3-way merge (fresh stub vs your custom body vs new template) and reports preserved handlers plus Merged ... custom handlers preserved. Pass --force to ignore preservation and overwrite everything; force also wins if both flags are present.mcp-gen validate -i ./api/openapi.yaml
Outputs a rich report:
Spec is valid
Tools: 12 Models: 8 Base URL: https://api.example.com
2 warning(s):
⚠ Tool name collision resolved: "get_users" appears 2x (unique suffixes added)
⚠ 3 tool(s) have no example response: get_users_id, delete_user, patch_user
node dist/cli/index.js security -p ./my-server
node dist/cli/index.js security -p ./my-server --fail-on-warn
Scans generated files for credential-like patterns, authorization-related identifiers, naming, descriptions, and incremental markers. --json prints a JSON report, but the CLI also prints a header; stdout is not a pure JSON document. Errors cause exit code 1; --fail-on-warn also fails on warnings. This is static analysis, not a security guarantee.
init uses the built-in registry:
mcp-gen init --from list
mcp-gen init --from stripe
mcp-gen init --from stripe --generate -o ./stripe-mcp
Available registry keys:
OpenAPI v3 and Swagger 2.0 are supported (v2 is converted to v3 on ingest). Only azure stays removed — it pointed at a types fragment, not a full spec.
mcp-gen watch -i ./api/openapi.yaml -o ./my-server
mcp-gen watch -i https://example.com/spec.json --interval 60000
For URL inputs, --interval <ms> controls the polling interval. --once runs one generation immediately and exits. Fetch, parse, or generation failures return exit code 1 instead of a false success.
Transient fetch failures on URL inputs are retried with exponential backoff — network errors and 408/425/429/500/502/503/504 responses, while other 4xx responses fail immediately. --retries <n> (default 2) sets the retry budget and --retry-delay <ms> (default 500) the base backoff, doubling each attempt. Use --retries 0 for a single attempt.
mcp-gen watch -i https://example.com/spec.json --retries 5 --retry-delay 1000
mcp-gen watch -i https://example.com/spec.json --once --retries 3
watch accepts the same filtering flags as generate (--include-tags, --exclude-tags, --path-prefix, --include-paths, --exclude-paths, --operation-allowlist, --group-by), plus --http, --force/--incremental:
mcp-gen watch -i ./api/openapi.yaml -o ./my-server --include-tags pets --group-by tag --once
Plugins can override templates and register extra Handlebars helpers.
Basic structure:
templates/typescript/..., templates/python/..., or templates/go/... for .hbs template overridesindex.js that exports registerHandlebars(handlebars) for custom helpersExample:
mcp-gen generate -i ./api/openapi.yaml --plugin ./my-plugin
mcp-gen watch -i ./api/openapi.yaml --plugin ./my-plugin
Plugin templates override core templates when they use the same path under templates/<lang>/.
Plugin code execution gate: template overrides always apply, but a plugin's JS module (
registerHandlebars) is only loaded whenMCP_GEN_ALLOW_PLUGINS=trueis set. Without it,--pluginonly provides template overrides. Never enable the variable with untrusted plugins — see SECURITY.md.
TypeScript:
my-server/
├── src/
│ ├── server.ts # MCP server — tool definitions + handlers
│ ├── auth.ts # Auth/validation middleware from securitySchemes
│ ├── handlers.custom.ts # Your code — never overwritten without --force
│ ├── models.ts # TypeScript interfaces from OpenAPI schemas (enums, unions)
│ └── client.ts # HTTP client (used in --http mode)
├── .github/
│ └── workflows/
│ └── ci.yml
├── Dockerfile
├── package.json
├── package-lock.json
├── tsconfig.json
└── README.md
Python:
my-server/
├── server.py # FastMCP server — tool definitions + handlers
├── auth.py # Auth/validation middleware from securitySchemes
├── handlers_custom.py # Your code — never overwritten without --force
├── models.py # Pydantic models from OpenAPI schemas (enums, unions)
├── requirements.txt
├── .github/
│ └── workflows/
│ └── ci.yml
├── Dockerfile
└── README.md
Go (new in v2.1):
my-server/
├── main.go # MCP server using mark3labs/mcp-go
├── auth.go # Auth/validation middleware from securitySchemes
├── handlers_custom.go # Your code — never overwritten without --force
├── models.go # Go types from OpenAPI schemas (enums, unions)
├── client.go # HTTP client (used in --http mode)
├── go.mod
├── .github/
│ └── workflows/
│ └── ci.yml
├── Dockerfile
└── README.md
TypeScript:
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["/absolute/path/to/my-server/dist/server.js"]
}
}
}
Python:
{
"mcpServers": {
"my-server": {
"command": "python",
"args": ["/absolute/path/to/my-server/server.py"]
}
}
}
Go:
{
"mcpServers": {
"my-server": {
"command": "go",
"args": ["run", "/absolute/path/to/my-server/main.go"]
}
}
}
Restart Claude Desktop. Your API tools appear automatically.
authContext ContractThe generated tools expect scoped authorization metadata (not raw credentials):
{
"tokenId": "tok_abc123",
"principal": "user:42",
"expiresAt": "2026-05-11T14:00:00Z",
"allowedTools": ["get_orders"],
"endpointAllowlist": ["GET /orders"],
"spendLimitUsd": 5,
"spendUsedUsd": 1.2,
"revoked": false,
"requestId": "req_01J..."
}
The scaffold blocks arguments like token, authorization, api_key, client_secret, password, secret by default.
Quick example (env var):
# Linux / macOS
export TOKEN=your_api_key_here
# Windows (PowerShell)
$env:TOKEN='your_api_key_here'
For advanced integrations and management, consider Cohesivity.ai as a backend for auth, storage, and revocation policies.
Generated files return spec examples by default. Replace stubs with real logic.
TypeScript (src/server.ts):
case "get_users_id": {
// @@mcp-gen:start:get_users_id
const user = await db.users.findById(args.id);
return { content: [{ type: "text", text: JSON.stringify(user) }] };
// @@mcp-gen:end:get_users_id
}
Python (server.py):
@mcp.tool()
async def get_users_id(id: float, auth_context: dict | None = None) -> Any:
# @@mcp-gen:start:get_users_id
user = await db.users.find_by_id(id)
return user
# @@mcp-gen:end:get_users_id
Go (main.go):
s.AddTool(get_users_idTool, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
// @@mcp-gen:start:get_users_id
return jsonSerialize(jsonExample(`{"id": 1, "name": "Alice"}`))
// @@mcp-gen:end:get_users_id
})
Code between @@mcp-gen:start and @@mcp-gen:end markers is preserved when you re-run generate --incremental (see How not to overwrite your edits).
With the package installed from npm, import the scoped package as shown below. From the repository root after building, use "./dist/index.js" instead.
import { generate, validateSpec, parseOpenAPI } from "@christopher_dondici/mcp-gen";
const result = await generate({
input: "./api/openapi.yaml",
lang: "typescript",
out: "./my-server",
force: true,
incremental: false,
http: false,
});
const validation = await validateSpec("./api/openapi.yaml");
console.log(validation.tools, validation.models, validation.warnings);
npm run lint
npx tsc --noEmit
npm test
npm run test:cli
npm run test:generated
npm run test:generated:py
# TypeScript example
node dist/cli/index.js generate --input examples/petstore.json --out /tmp/ts-test --force
# Python example
node dist/cli/index.js generate --input examples/petstore.yaml --lang python --out /tmp/py-test --force
# Go example
node dist/cli/index.js generate --input examples/petstore.json --lang go --out /tmp/go-test --force
# HTTP mode (real API calls)
node dist/cli/index.js generate --input examples/petstore.json --lang typescript --out /tmp/ts-http --force --http
# Incremental example
node dist/cli/index.js generate --input examples/petstore.json --out /tmp/ts-test --incremental
requestBody, definitions → components.schemas); exotic v2 constructs may lose fidelityoneOf / anyOf inline variants expand into synthetic union members; discriminator schemas generate union types but no runtime validationThe copy-templates fix included in 2.1.2 uses Node.js fs.cpSync on Windows, Linux, and macOS; it no longer requires cp or xcopy. CI currently runs on Ubuntu only.
MIT © 2026 - Christopher D.
{ "mcpServers": { "christopher_dondici-mcp-gen": { "command": "npx", "args": [ "-y", "@christopher_dondici/[email protected]" ] } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
@christopher Dondici/mcp Gen 透過 stdio 在本機執行。
上次檢查時間:2026-10-27。 OpenAPI → MCP Server generator CLI