mcpgen

---

Aponte mcpgen para uma especificação OpenAPI ou coleção do Postman. Receba um servidor MCP Python completo que é seu — sem dependência de runtime do mcpgen, sem proxy, sem lock-in. Leia. Modifique. Implante.

---

Instalação

pip install mcpgen-cli

Início 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"

É isso. mcpgen lê sua especificação e grava um servidor MCP Python no disco.

---

O que você obtém

Um diretório autocontido com código-fonte que é seu:

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

Execute imediatamente:

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

O server.py gerado se parece com isto:

#!/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))

Sem caixa-preta. Sem dependências em tempo de execução. Apenas Python.

---

Adicionar ao Claude Desktop

mcpgen imprime o trecho de configuração exato para colar no seu 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" }
    }
  }
}

Localização do arquivo de configuração:

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

---

Por que código-fonte em vez de um proxy?

A maioria das ferramentas de API para MCP são proxies de runtime — elas ficam entre o Claude e sua API para sempre, e você depende delas para continuar funcionando.

mcpgen gera código-fonte que é seu. A saída é um arquivo Python simples. Você pode:

• Ler cada linha do que está acontecendo
• Modificar a lógica de autenticação, adicionar tentativas, ajustar o tratamento de erros
• Implantá-lo em qualquer lugar sem qualquer dependência de mcpgen
• Enviá-lo para seu próprio repositório, versioná-lo, revisá-lo em PRs

mcpgen é uma ferramenta de build. Necessária apenas uma vez, no momento da geração. Nunca em tempo de execução.

---

Entradas suportadas

Formato	Exemplo
OpenAPI 3.x JSON	mcpgen openapi.json
OpenAPI 3.x YAML	mcpgen api.yaml
URL apontando para especificação OpenAPI	mcpgen https://api.example.com/openapi.json
Postman Collection v2.1	mcpgen collection.json

Testado com:

• Petstore — 19 endpoints → 19 ferramentas
• GitHub REST API (subset)
• Stripe API (subset)
• Qualquer especificação OpenAPI 3.x válida

---

Suporte a autenticação

mcpgen detecta automaticamente o esquema de autenticação da sua API a partir da especificação:

Esquema	Declaração OpenAPI	Variável de ambiente gerada
Bearer token	type: http, scheme: bearer	YOUR_API_TOKEN
API Key	type: apiKey	YOUR_API_API_KEY
Basic Auth	type: http, scheme: basic	YOUR_API_CREDENTIALS
None	No securitySchemes	—

Fluxos OAuth2 são aproximados como token bearer — você fornece o token manualmente.

---

Referência da 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

---

Roteiro

• Saída TypeScript (--lang ts) usando @modelcontextprotocol/sdk
• Suporte a Swagger 2.x (detecção automática, parser separado)
• Detectar automaticamente URL OpenAPI a partir do domínio base (/.well-known/openapi.json, /api-docs, etc.)
• Flag --update-claude-config para corrigir claude_desktop_config.json automaticamente
• Resolução recursiva de $ref para esquemas profundamente aninhados

PRs são bem-vindos. Veja CONTRIBUTING.md.

---

Contribuindo

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

O código tem três camadas limpas:

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 adicionar um novo formato de entrada: escreva um parser que retorne MCPSpec. Nada mais muda. Para adicionar uma nova linguagem de saída: escreva um gerador que consuma MCPSpec. Nada mais muda.

---

Licença

MIT — o código gerado é seu para fazer o que quiser.