mcpgen

Turn any OpenAPI spec or Postman collection into an ownable Python MCP server in 30 seconds

Comment

mcpgen

Inspiration

Every developer building with Claude or other LLMs faces the same painful bottleneck: connecting AI to real APIs requires writing boilerplate MCP servers from scratch.

Hours of repetitive code for every single API.

I wanted to reduce that to 30 seconds — and ensure developers own the generated code, with no runtime proxy, no lock-in, and no black box.

What it Does

mcpgen takes any OpenAPI 3.x specification (JSON/YAML, local file, or URL) or Postman collection and generates a complete, standalone Python MCP server.

One command, and you have a working bridge between Claude and any REST API.

The generated server.py is yours — read it, modify it, deploy it anywhere.

mcpgen is only needed for generation and is never required at runtime.

pip install mcpgen
mcpgen https://petstore3.swagger.io/api/v3/openapi.json

How We Built It

  • Python 3.10+
  • Typer for the CLI
  • Rich for beautiful terminal output
  • Pydantic v2 for the internal representation (IR) layer
  • Jinja2 templates for clean and customizable code generation
  • httpx for async HTTP requests with connection pooling
  • Pytest with 17 tests covering parsers, generators, and CLI integration

  • OpenAPI 3.x parser supporting:

    • Paths
    • Parameters
    • Request bodies
    • Authentication detection

Supported Authentication Types

  • Bearer Token
  • API Key (Header)
  • Basic Authentication

Challenges We Ran Into

Relative URL Resolution

Many OpenAPI specifications (such as Petstore) use relative server URLs:

/api/v3

We implemented URL joining against the source URL to produce valid base URLs automatically.

Authentication Detection

OpenAPI security schemes vary widely.

We built a resolver that supports:

  • Bearer Authentication
  • API Key Authentication
  • Basic Authentication

It also generates environment variable names automatically.

PyPI Naming Conflict

The name mcpify was already taken by another project.

We renamed the package to mcpgen and updated:

  • Source code
  • Documentation
  • CI/CD configuration
  • README references

Template Escaping

Generated code contains path parameters such as:

{id}

Jinja2 templates required careful escaping of curly braces.

This was solved using explicit Jinja raw blocks.

Accomplishments We're Proud Of

Zero Runtime Dependency

mcpgen generates code that developers fully own.

There is:

  • No runtime proxy
  • No lock-in
  • No external service dependency

This is the primary differentiator from other API-to-MCP tools.

Beautiful CLI Experience

Features include:

  • Progress indicators
  • Colored terminal output
  • Auto-generated Claude Desktop configuration snippets

The tool feels polished from the first command.

Comprehensive Testing

  • 17 passing tests
  • Coverage for parsers
  • Coverage for generators
  • Coverage for CLI integration

Shared AsyncClient

Generated servers include a shared httpx.AsyncClient.

Benefits:

  • Connection pooling
  • Improved performance
  • Reduced resource usage

Multiple Input Formats

Supported from version 0.1.0:

  • OpenAPI JSON
  • OpenAPI YAML
  • Remote OpenAPI URLs
  • Postman Collections

What We Learned

Code Generation Beats Runtime Proxies

Developers prefer owning and modifying generated code rather than depending on external services.

This insight shaped the entire architecture.

Decouple Parsers from Generators

Using an Intermediate Representation (IR) layer makes it easy to add:

  • New input formats
  • New output languages
  • Additional generators

without modifying existing components.

Launch Preparation Is a Feature

Things that matter:

  • README quality
  • Badges
  • Demo GIFs
  • CI pipelines
  • PyPI packaging

These influence adoption as much as code quality.

The MCP Ecosystem Needs Better Tooling

The gap between:

"I have an API"

and

"Claude can use it"

is still too large.

mcpgen significantly narrows that gap.

What's Next for mcpgen

TypeScript Output

--lang ts

Generate MCP servers using:

@modelcontextprotocol/sdk

Swagger 2.x Support

Millions of APIs still rely on Swagger 2.x.

Recursive $ref Resolution

Support deeply nested OpenAPI schemas.

Automatic OpenAPI Discovery

Point mcpgen at a domain and automatically locate the OpenAPI specification.

Web Playground

Paste an OpenAPI URL and instantly generate an MCP server directly in the browser.

No installation required.

Enterprise Features

Planned additions include:

  • Custom authentication modules
  • Batch generation
  • CI/CD integration
  • Enterprise deployment workflows

Conclusion

mcpgen transforms API integration with LLMs from hours of manual MCP server development into a process that takes seconds.

Developers maintain full ownership of the generated code while benefiting from a streamlined, production-ready workflow.

Built With

Share this project:

Updates