mcpgen

---

Apunta mcpgen a una especificación OpenAPI o colección de Postman. Obtén un servidor MCP Python completo que te pertenece — sin dependencia de tiempo de ejecución de mcpgen, sin proxy, sin bloqueo. Léelo. Modifícalo. Despliégalo.

---

Instalación

pip install mcpgen-cli

Inicio rápido

# From a URL
mcpgen https://petstore3.swagger.io/api/v3/openapi.json

# From a local OpenAPI file (JSON or YAML)
mcpgen stripe.yaml

# From a Postman collection
mcpgen postman_collection.json

# Preview without writing anything
mcpgen openapi.json --dry-run

# Custom output directory and server name
mcpgen openapi.json --output ~/my-mcp-servers --name "My API"

Eso es todo. mcpgen lee tu especificación y escribe un servidor MCP Python en el disco.

---

Lo que obtienes

Un directorio autocontenido con código fuente que te pertenece:

stripe_api_mcp/
├── server.py          ← the MCP server (read it, edit it, it's yours)
└── requirements.txt   ← httpx, mcp

Ejecútalo inmediatamente:

cd stripe_api_mcp
pip install -r requirements.txt
export STRIPE_API_TOKEN="sk_live_..."
python server.py

El server.py generado se ve así:

#!/usr/bin/env python3
"""
Stripe API MCP Server
Generated by mcpgen — https://github.com/JnanaSrota/mcpgen
This file is yours. Modify it freely.
"""
import os, asyncio, httpx
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp import types

BASE_URL = "https://api.stripe.com"
AUTH_TOKEN = os.environ.get("STRIPE_API_TOKEN", "")

app = Server("stripe-api")

@app.call_tool()
async def _handle_get_customers(name: str, arguments: dict):
    if name != "get_customers":
        raise ValueError(f"Unknown tool: {name}")
    url = BASE_URL + "/v1/customers"
    query_params = {}
    if "limit" in arguments:
        query_params["limit"] = arguments["limit"]
    async with httpx.AsyncClient(timeout=30.0) as client:
        response = await client.get(url, params=query_params,
            headers={"Authorization": f"Bearer {AUTH_TOKEN}"})
        response.raise_for_status()
        return [types.TextContent(type="text", text=response.text)]

# ... one function per API endpoint

@app.list_tools()
async def list_tools(): ...

if __name__ == "__main__":
    asyncio.run(stdio_server(app))

Sin caja negra. Sin dependencias en tiempo de ejecución. Solo Python.

---

Añadir a Claude Desktop

mcpgen imprime el fragmento de configuración exacto para pegar en tu claude_desktop_config.json:

{
  "mcpServers": {
    "stripe-api-mcp": {
      "command": "python",
      "args": ["/path/to/stripe_api_mcp/server.py"],
      "env": { "STRIPE_API_TOKEN": "your-key-here" }
    }
  }
}

Ubicación del archivo de configuración:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

---

¿Por qué código fuente en lugar de un proxy?

La mayoría de las herramientas de API a MCP son proxies de tiempo de ejecución — se interponen entre Claude y tu API para siempre, y dependes de que sigan funcionando.

mcpgen genera código fuente que te pertenece. La salida es un archivo Python simple. Puedes:

• Leer cada línea de lo que sucede
• Modificar la lógica de autenticación, añadir reintentos, ajustar el manejo de errores
• Desplegarlo en cualquier lugar sin ninguna dependencia de mcpgen
• Confirmarlo en tu propio repositorio, versionarlo, revisarlo en PRs

mcpgen es una herramienta de compilación. Se necesita una vez, en el momento de la generación. Nunca en tiempo de ejecución.

---

Entradas admitidas

Formato	Ejemplo
OpenAPI 3.x JSON	mcpgen openapi.json
OpenAPI 3.x YAML	mcpgen api.yaml
URL que apunta a la especificación OpenAPI	mcpgen https://api.example.com/openapi.json
Colección Postman v2.1	mcpgen collection.json

Probado con:

• Petstore — 19 endpoints → 19 herramientas
• API REST de GitHub (subconjunto)
• API de Stripe (subconjunto)
• Cualquier especificación OpenAPI 3.x válida

---

Soporte de autenticación

mcpgen detecta automáticamente el esquema de autenticación de tu API a partir de la especificación:

Esquema	Declaración OpenAPI	Variable de entorno generada
Token Bearer	type: http, scheme: bearer	YOUR_API_TOKEN
Clave API	type: apiKey	YOUR_API_API_KEY
Autenticación básica	type: http, scheme: basic	YOUR_API_CREDENTIALS
Ninguno	No securitySchemes	—

Los flujos OAuth2 se aproximan como token Bearer — tú proporcionas el token manualmente.

---

Referencia de CLI

Usage: mcpgen [OPTIONS] INPUT

  Turn any API into an MCP server in 30 seconds.

Arguments:
  INPUT  OpenAPI JSON/YAML file, Postman collection, or URL  [required]

Options:
  -o, --output PATH   Output directory (default: current directory)
  -n, --name TEXT     Override the generated server name
  --dry-run           Print generated code without writing files
  --no-color          Disable colored output
  -v, --version       Show version and exit
  --help              Show this message and exit

---

Hoja de ruta

• Salida TypeScript (--lang ts) usando @modelcontextprotocol/sdk
• Soporte Swagger 2.x (detección automática, analizador separado)
• Detectar automáticamente la URL de OpenAPI desde el dominio base (/.well-known/openapi.json, /api-docs, etc.)
• Indicador --update-claude-config para parchear claude_desktop_config.json automáticamente
• Resolución recursiva de $ref para esquemas profundamente anidados

Se aceptan PRs. Consulta CONTRIBUTING.md.

---

Contribuciones

git clone https://github.com/JnanaSrota/mcpgen
cd mcpgen
pip install -e ".[dev]"
pytest tests/ -v

El código base tiene tres capas limpias:

Input (file / URL)
    ↓
loader.py              ← detects format, routes to correct parser
    ↓
openapi.py / postman.py   ← parse to MCPSpec (internal IR)
    ↓
generator/python.py       ← renders Jinja2 templates → server.py

Para añadir un nuevo formato de entrada: escribe un analizador que devuelva MCPSpec. Nada más cambia. Para añadir un nuevo lenguaje de salida: escribe un generador que consuma MCPSpec. Nada más cambia.

---

Licencia

MIT — el código generado es tuyo para hacer lo que quieras con él.