OpenAPI to MCP
ReflexUK/openapi-to-mcp
Transforma OpenAPI specs em ferramentas MCP para LLMs instantaneamente
Ver no GitHubConverte especificações OpenAPI 3.x em servidores MCP prontos para uso com Claude e outros clientes. Cada endpoint da API se torna automaticamente uma ferramenta que o LLM pode chamar, eliminando a necessidade de código de integração manual.
Instalação
npx convez-ai ReflexUK/openapi-to-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Integrar APIs REST existentes com Claude Desktop sem escrever wrappers
- Expor múltiplos endpoints de uma API como tools em um MCP server
- Adicionar autenticação (Bearer token ou headers customizados) a chamadas de API
Veredito

Ferramenta sólida que resolve um problema real: conectar APIs REST a LLMs sem boilerplate. Implementação madura com suporte a autenticação, headers customizados e tanto CLI quanto uso programático. Ideal para quem quer expor APIs legadas ao ecossistema MCP.
README
A tradução para o português deste README ainda está na fila.
openapi-to-mcp
Turn any OpenAPI 3.x spec into a Model Context Protocol server -- every endpoint becomes a tool your LLM can call. No glue code.
Point it at a spec (file or URL), and every operation shows up as an MCP tool in Claude Desktop, Codex, or any MCP client. Path/query/header params and JSON request bodies are mapped automatically. Inline $ref schemas are resolved so tools always receive fully-materialized schemas.
OpenAPI spec --> openapi-to-mcp --> MCP tools --> Claude / Codex / any MCP client
Why
Wiring an existing REST API into an LLM normally means hand-writing a tool wrapper per endpoint. Most APIs already publish an OpenAPI spec -- this reads it and generates the tools at runtime, so a 200-endpoint API is one command, not 200 functions.
Install
npm install -g openapi-to-mcp
# or run without installing:
npx openapi-to-mcp <spec>
Quick start
Inspect the tools a spec produces (no server, no network):
openapi-to-mcp examples/petstore.json --list
Swagger Petstore v1.0.0 -- 2 tools
findPetsByStatus (GET /pet/findByStatus)
getPetById (GET /pet/{petId})
Serve it over stdio (how MCP clients connect):
openapi-to-mcp https://petstore3.swagger.io/api/v3/openapi.json
Use with Claude Desktop / Codex
Add to your MCP client config (Claude Desktop: claude_desktop_config.json):
{
"mcpServers": {
"petstore": {
"command": "npx",
"args": ["-y", "openapi-to-mcp", "https://petstore3.swagger.io/api/v3/openapi.json"]
}
}
}
Restart the client and the API endpoints appear as callable tools.
Authentication
Most APIs need a token. Two ways, neither puts secrets in the spec:
# Bearer token via env (sent as "Authorization: Bearer <token>")
OPENAPI_MCP_TOKEN=sk-xxx openapi-to-mcp ./api.yaml
# Arbitrary headers (repeatable)
openapi-to-mcp ./api.yaml --header "X-Api-Key: abc123" --header "X-Org: acme"
CLI reference
| Flag | Description |
|---|---|
<spec> / --spec <path|url> | OpenAPI 3.x spec, JSON or YAML, local or remote |
--base-url <url> | Override the base URL from the spec's servers |
--header "K: V" | Add a header to every request (repeatable) |
--timeout <ms> | Per-request timeout in milliseconds (default: 30000) |
--list | Print discovered tools and exit |
-h, --help | Show help |
| Env | Description |
|---|---|
OPENAPI_MCP_TOKEN | Sent as Authorization: Bearer <token> |
Programmatic use
import { loadSpec, extractDocument, createServer } from "openapi-to-mcp";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const doc = extractDocument(await loadSpec("./api.yaml"), { specUrl: "./api.yaml" });
const server = createServer(doc, {
headers: { "X-Api-Key": process.env.KEY! },
timeoutMs: 10_000,
});
await server.connect(new StdioServerTransport());
How it works
- Load the spec from a path or URL (JSON or YAML).
- Resolve inline
$refpointers in parameter and request body schemas so tools always get complete type information. - Extract every
pathx HTTP method into a normalized operation, deriving a stable tool name fromoperationId(ormethod_path). - Map path/query/header params and the JSON request body into a single JSON Schema per tool.
- Serve over MCP stdio. A tool call rebuilds the HTTP request -- substituting path params, appending query strings, setting headers -- and returns the response. Requests are aborted after
--timeoutms (default 30s).
Limitations
- OpenAPI 3.x only (not Swagger 2.0).
- Only local (same-document)
$refs are resolved. External file or URL refs are not fetched. - JSON request bodies only (
application/json). - Cookie parameters are ignored.
PRs welcome for any of these.
Development
npm install
npm test # node:test, no network required
npm run build # tsc -> dist/
License
MIT (c) ReflexUK