🚀 OpenAPI to MCP Server Code Generator

---

Easily generate a Model Context Protocol (MCP) server from any OpenAPI specification!

This tool helps you bootstrap new MCP servers for any API with an OpenAPI spec.

---

✨ Features

• ⚡ Automatic MCP server generation from OpenAPI specs
• 📝 Supports JSON and YAML formats
• 🔍 Auto-detects spec file type (.json, .yaml, .yml)
• 🛠️ Tool modules for each API endpoint
• 🤖 API client code generation
• 📋 Logging & error handling setup
• ⚙️ Configuration files (pyproject.toml, .env.example)
• 📚 Comprehensive documentation generation
• 🤖 Enhanced Docstrings via LLM integration
• 🚀 --generate-agent flag – additionally produces a LangGraph React agent (with A2A server, Makefile, README and .env.example) alongside the generated MCP server.

---

📦 Requirements

• 🐍 Python 3.13+
• ⚡ pipx (recommended)
• 🧪 Optional: Poetry for local development

---

⚡ Quick Start with pipx (Recommended)

pipx run --spec git+https://github.com/cnoe-io/openapi-mcp-codegen.git@main openapi_mcp_codegen \
  --spec-file examples/petstore/openapi_petstore.json \
  --output-dir examples/petstore/mcp_server \
  --generate-agent

📌 Optional: Pin a release tag

pipx run --spec git+https://github.com/cnoe-io/openapi-mcp-codegen.git@v0.1.0 openapi_mcp_codegen \
  --spec-file examples/petstore/openapi_petstore.json \
  --output-dir examples/petstore/mcp_server \
  --generate-agent

🤖 Optional: Enhance Docstrings via LLM

Use the --enhance-docstring-with-llm flag if you want to improve generated docstrings with an LLM. This option leverages your LLM provider's configuration via environment variables.
To set up your LLM provider, refer to this guide.

pipx run --spec git+https://github.com/cnoe-io/openapi-mcp-codegen.git@main openapi_mcp_codegen \
  --spec-file examples/petstore/openapi_petstore.json \
  --output-dir examples/petstore/mcp_server \
  --generate-agent \
  --enhance-docstring-with-llm  # Optional: enhances docstrings using LLM (see guide)

---

🧑‍💻 Local Development

Prefer to run locally or contribute?

1. Clone the repo:

git clone https://github.com/cnoe-io/openapi-mcp-codegen
cd openapi-mcp-codegen

2. Install dependencies with Poetry:

poetry install

3. Run the generator:

• The generator will create code in a new directory called mcp_<server-name> in the directory you specify.
• Follow the setup instructions printed by the generator.

Option 1:

make generate -- --spec-file examples/petstore/openapi_petstore.json --output-dir examples/petstore/mcp_server

Option 2:

poetry run openapi_mcp_codegen --spec-file examples/petstore/openapi_petstore.json --output-dir examples/petstore/mcp_server

---

🗂️ Generated MCP Server Structure

mcp_petstore/
├── mcp_petstore/
│   ├── __init__.py
│   ├── api/
│   │   ├── __init__.py
│   │   └── client.py
│   ├── models/
│   │   ├── __init__.py
│   │   └── [models].py
│   ├── server.py
│   ├── tools/
│   │   ├── __init__.py
│   │   └── [tools].py
│   └── utils/
│       └── __init__.py
├── poetry.lock
├── pyproject.toml
└── README.md

🛠 Working with the generated agent

When you run the generator with --generate-agent, the output directory also contains:

• agent.py – LangGraph wrapper
• protocol_bindings/a2a_server/ – runnable A2A server
• Makefile, README.md, .env.example

Example:

cd examples/petstore/mcp_server
cp .env.example .env         # add {{ MCP_NAME | upper }}_API_URL & TOKEN
make run-a2a                 # start the A2A server

# In another terminal:
make run-a2a-client          # docker chat client

---

🛠️ Customization

• ✏️ Modify generated tool modules in tools/
• 🧩 Add custom models in models/
• 🔌 Extend the API client in api/client.py
• 🛠️ Add utility functions in utils/

---

👥 Maintainers

See MAINTAINERS.md

---

🤝 Contributing

See CONTRIBUTING.md

---

📄 License

Apache 2.0

---

🔒 Security

If you discover a security vulnerability, please see our SECURITY.md for responsible disclosure guidelines.

---

🧑‍💼 Code of Conduct

This project follows the Contributor Covenant Code of Conduct.

---

🙏 Acknowledgements

• MCP on PyPI, the official Model Context Protocol (MCP) Python package
• Thanks to the MCP community for their support
• Built with Poetry, uv, and open source love 💜