convez.ai
MCP ServerIntegração & APIsIntermediário
ReflexUK

OpenAPI to MCP

ReflexUK/openapi-to-mcp

Transforma OpenAPI specs em ferramentas MCP para LLMs instantaneamente

Ver no GitHub
InicialPluginScore · de 0 a 100

Converte 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-mcp

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

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

CI npm License: MIT

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

FlagDescription
<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)
--listPrint discovered tools and exit
-h, --helpShow help
EnvDescription
OPENAPI_MCP_TOKENSent 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

  1. Load the spec from a path or URL (JSON or YAML).
  2. Resolve inline $ref pointers in parameter and request body schemas so tools always get complete type information.
  3. Extract every path x HTTP method into a normalized operation, deriving a stable tool name from operationId (or method_path).
  4. Map path/query/header params and the JSON request body into a single JSON Schema per tool.
  5. 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 --timeout ms (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

Ver o original no GitHub

Bom para

Relacionados