MCP Toolbox

Generate production-ready MCP servers from OpenAPI specs in one command.

Quick Start

pip install -e ".[dev]"
mcp-toolbox generate --spec tests/fixtures/petstore.yaml -o ./output
cd output && pip install -e .

Features

• OpenAPI 3.0/3.1 validation with clear error reporting
• YAML, JSON, local files, and URL inputs
• $ref resolution with prance (including external refs)
• Typed OpenAPI parsing with openapi-pydantic
• Deterministic tool/model ordering and snapshot-backed generation checks
• Structured JSON tool outputs using Pydantic v2 TypeAdapter
• Generated Pydantic models from components/schemas
• Request-body generation for JSON, multipart/form-data, and application/x-www-form-urlencoded
• Retry/backoff-aware HTTP client with env-configurable timeout + retry settings
• Auth scaffolding for bearer, oauth2, api key (header/query/cookie), and basic
• Tool curation with explainable selection (preview --explain-selection)
• Template override support with --template-dir
• Config precedence: CLI > env (MCP_TOOLBOX_*) > pyproject.toml ([tool.mcp_toolbox]) > defaults
• Optional watch mode for local specs (mcp-toolbox watch)

Example Generated Output

@mcp.tool(structured_output=True)
async def list_pets(limit: int | None = 20, offset: int | None = 0) -> list[dict[str, Any]]:
    """List pets"""
    response = await request_with_retry(
        ctx.client,
        "GET",
        "/pets",
        max_retries=ctx.max_retries,
        backoff_seconds=ctx.backoff_seconds,
        request_kwargs={"params": {"limit": limit, "offset": offset}},
    )
    response.raise_for_status()
    return TypeAdapter(list[dict[str, Any]]).validate_python(response.json())

CLI Options (generate)

Option	Description	Default
<spec> or --spec	Path or URL to OpenAPI spec	required (provide one)
-o, --output	Output directory for generated server	./output
-n, --name	Override auto-detected server name	auto
--max-tools	Maximum number of generated tools	12
--tag, --filter-tags	Include only matching tags (repeatable)	none
--include-tags	Include tools by tag (repeatable)	none
--exclude-tags	Exclude tools by tag (repeatable)	none
--prefer-tags	Prioritize these tags during tool trimming	none
--body-style	Preferred request body style (auto/json/form/multipart)	auto
--enums	Enum style (literal/strenum)	literal
--dry-run	Analyze only, do not write files	false
--transport-default, --transport	Default transport embedded in generated server.py	stdio
--template-dir	Override built-in templates with local files	none

watch command is available for local specs:

mcp-toolbox watch --spec tests/fixtures/petstore.yaml -o ./output

CI-Friendly Commands

python -m pip install -e ".[dev]"
python -m ruff check .
python -m ruff format . --check
python -m pytest -q

Docs

• Gap analysis: docs/v2-gap-analysis.md
• Template authoring: docs/template-authoring.md
• Troubleshooting: docs/troubleshooting.md

Comparison

Capability	MCP Toolbox	Hand-written MCP server	Generic OpenAPI client generator
One-command MCP server generation	✅	❌	❌
MCP tool naming + descriptions	✅	manual	❌
OpenAPI validation + parsing pipeline	✅	manual	partial
FastMCP-ready async server scaffold	✅	manual	❌
Customizable templates	✅	n/a	limited

Current Limitations

• oneOf / anyOf are mapped to Python unions but complex discriminator behavior is still best-effort.
• XML/custom media types are not deeply modeled (JSON/form flows are primary).
• OAuth2 client-credentials generation provides scaffold/env wiring; full token lifecycle automation is left to integrators.

Contributing

1. Fork the repo
2. Create a branch: git checkout -b feature/my-change
3. Run checks: python -m ruff check . && python -m pytest -q
4. Open a pull request

License

MIT — see LICENSE.