mcp-openapi

Transforme qualquer especificação OpenAPI/Swagger em ferramentas Claude. Zero configuração, zero código.

Documentação

mcp-openapi

Transforme qualquer especificação OpenAPI/Swagger em ferramentas MCP — para que o Claude e outros assistentes de IA possam chamar suas APIs REST.

Aponte o mcp-openapi para qualquer URL de especificação OpenAPI 3.x ou Swagger 2.0 e ele gera ferramentas do Model Context Protocol (MCP) automaticamente. Sem geração de código, sem arquivos de configuração, sem código boilerplate. Seu assistente de IA obtém ferramentas chamáveis para cada endpoint de API em segundos.

Início Rápido

1. Execute (sem necessidade de instalação):

npx mcp-openapi --spec https://petstore3.swagger.io/api/v3/openapi.json

2. Adicione ao Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "petstore": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://petstore3.swagger.io/api/v3/openapi.json"
      ]
    }
  }
}

3. Peça ao Claude para usar:

"Liste todos os pets disponíveis na loja"

O Claude vê ferramentas MCP como find_pets_by_status, get_pet_by_id, add_pet e as chama diretamente.

Por que mcp-openapi?

A maioria das pontes MCP-para-API exige que você escreva definições de ferramentas manualmente ou gere código a partir de uma especificação. O mcp-openapi elimina tudo isso.

Recurso	mcp-openapi	Servidores MCP escritos à mão	Ferramentas HTTP genéricas
Configuração zero	Sim	Não	Parcial
OpenAPI 3.x + Swagger 2.0	Sim	N/A	N/A
Esquemas de parâmetros planos (otimizados para LLM)	Sim	Manual	Não
Nomenclatura inteligente de ferramentas a partir do operationId	Sim	Manual	Não
Autenticação (API key, Bearer, OAuth2)	Integrada	Faça você mesmo	Faça você mesmo
Tentativas com backoff exponencial	Integrado	Faça você mesmo	Faça você mesmo
Truncamento de resposta para contexto do LLM	Integrado	Faça você mesmo	Não

Esquemas de parâmetros planos são o principal diferencial. Em vez de passar objetos JSON aninhados (que os LLMs frequentemente erram), o mcp-openapi achata parâmetros de path, query, header e body em um único objeto plano. Isso melhora drasticamente a precisão das chamadas de ferramentas.

Como Funciona

OpenAPI/Swagger Spec          mcp-openapi               AI Assistant
     (URL or file)                                      (Claude, etc.)
          |                         |                         |
          |   1. Parse & validate   |                         |
          |------------------------>|                         |
          |                         |                         |
          |   2. Generate MCP tools |                         |
          |   (one per endpoint)    |                         |
          |------------------------>|                         |
          |                         |                         |
          |                         |   3. Register tools     |
          |                         |   via stdio transport   |
          |                         |------------------------>|
          |                         |                         |
          |                         |   4. AI calls a tool    |
          |                         |<------------------------|
          |                         |                         |
          |   5. Build & execute    |                         |
          |   HTTP request          |                         |
          |<------------------------|                         |
          |                         |                         |
          |   6. Return truncated   |                         |
          |   response to AI        |                         |
          |------------------------>|------------------------>|

Cada endpoint de API se torna uma ferramenta MCP:

Nome da ferramenta é derivado do operationId (convertido para snake_case) ou do method + path
Parâmetros são achatados em um único esquema de entrada (parâmetros de path, query, header e body mesclados)
Respostas são truncadas para ~50KB para permanecer dentro dos limites de contexto do LLM
Erros (429, 5xx) acionam tentativas automáticas com backoff exponencial (até 3 tentativas)

Integração com Claude Desktop

Adicione qualquer API ao Claude Desktop editando seu arquivo de configuração:

Localização:

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

API pública (sem autenticação)

{
  "mcpServers": {
    "petstore": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://petstore3.swagger.io/api/v3/openapi.json"
      ]
    }
  }
}

API com Bearer Token

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json",
        "--auth-type", "bearer",
        "--auth-token", "$GITHUB_TOKEN",
        "--prefix", "github",
        "--include", "listReposForAuthenticatedUser,getRepo,listIssues,createIssue"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

API com API Key

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://api.weather.example.com/openapi.json",
        "--auth-type", "api-key",
        "--auth-name", "X-API-Key",
        "--auth-value", "$WEATHER_API_KEY",
        "--auth-in", "header"
      ],
      "env": {
        "WEATHER_API_KEY": "your_key_here"
      }
    }
  }
}

Referência da CLI

npx mcp-openapi --spec <url-or-path> [options]

Opções Gerais

Opção	Curta	Padrão	Descrição
`--spec <url\|path>`	`-s`	obrigatório	URL da especificação OpenAPI ou caminho de arquivo local
`--config <path>`	`-c`		Caminho do arquivo de configuração JSON
`--base-url <url>`		da especificação	Substituir a URL base da API
`--prefix <name>`			Prefixo para todos os nomes de ferramentas (ex.: `github` -> `github_list_repos`)
`--include <patterns>`		todos	operationIds separados por vírgula para incluir
`--exclude <patterns>`		nenhum	operationIds separados por vírgula para excluir
`--timeout <ms>`		`30000`	Tempo limite de requisição HTTP em milissegundos
`--max-retries <n>`		`3`	Máximo de tentativas em respostas 429/5xx
`--header <name:value>`	`-H`		Cabeçalho personalizado (repetível)
`--transport <type>`		`stdio`	Tipo de transporte: `stdio` ou `sse`
`--port <n>`		`3000`	Porta para transporte SSE
`--help`	`-h`		Mostrar ajuda
`--version`	`-v`		Mostrar versão
`--license-key <key>`			Chave de licença Pro (ou env `$MCP_OPENAPI_LICENSE_KEY`)
`--server <selector>`		`0`	Selecionar servidor da API por índice, URL parcial ou URL exata
`--no-doc-warnings`			Suprimir avisos de qualidade de documentação na inicialização
`--dynamic-discovery`		automático (100+)	Habilitar descoberta dinâmica de ferramentas para APIs grandes

Opções de Autenticação

Bearer token:

Opção	Descrição
`--auth-type bearer`	Usar autenticação com Bearer token
`--auth-token <token>`	O valor do token (suporta sintaxe `$ENV_VAR`)

API key:

Opção	Descrição
`--auth-type api-key`	Usar autenticação com API key
`--auth-name <name>`	Nome do cabeçalho ou parâmetro de query
`--auth-value <value>`	O valor da API key (suporta sintaxe `$ENV_VAR`)
`--auth-in <header\|query>`	Onde enviar a chave (padrão: `header`)

Credenciais de cliente OAuth2:

Opção	Descrição
`--auth-type oauth2`	Usar fluxo de credenciais de cliente OAuth2
`--auth-client-id <id>`	ID do cliente OAuth2
`--auth-client-secret <secret>`	Segredo do cliente OAuth2
`--auth-token-url <url>`	URL do endpoint de token
`--auth-scopes <scopes>`	Escopos separados por vírgula

Exemplos da CLI

# Basic usage with a remote spec
npx mcp-openapi --spec https://petstore3.swagger.io/api/v3/openapi.json

# Local YAML spec with Bearer auth
npx mcp-openapi --spec ./api.yaml --auth-type bearer --auth-token '$API_KEY'

# Filter to specific endpoints with a prefix
npx mcp-openapi --spec ./api.json --prefix myapi --include 'listUsers,getUser'

# Override base URL (useful for local dev)
npx mcp-openapi --spec https://api.example.com/openapi.json --base-url http://localhost:3000

# Add custom headers
npx mcp-openapi --spec ./api.json -H 'X-Custom: value' -H 'X-Another: value2'

# Use a JSON config file
npx mcp-openapi --config ./mcp-config.json

# Select staging server
npx mcp-openapi --spec ./api.json --server staging

# Large API with dynamic discovery
npx mcp-openapi --spec https://api.stripe.com/openapi.json --dynamic-discovery

Formato do Arquivo de Configuração

Em vez de flags da CLI, você pode usar um arquivo de configuração JSON:

{
  "spec": "https://api.example.com/openapi.json",
  "prefix": "myapi",
  "include": ["listUsers", "getUser", "createUser"],
  "auth": {
    "type": "bearer",
    "token": "$API_TOKEN"
  },
  "timeout": 15000,
  "maxRetries": 2,
  "headers": {
    "X-Custom-Header": "value"
  }
}

Argumentos da CLI têm precedência sobre valores do arquivo de configuração.

Especificações Suportadas

Formato	Versões	Tipos de arquivo
OpenAPI	3.0.x, 3.1.x	`.json`, `.yaml`, `.yml`
Swagger	2.0	`.json`, `.yaml`, `.yml`

As especificações podem ser carregadas de:

URLs remotas (https://...)
Caminhos de arquivos locais (./api.yaml, /absolute/path/spec.json)

Recursos da v0.3.0

Avisos de Qualidade de Documentação

Na inicialização, o mcp-openapi verifica a qualidade da documentação de cada ferramenta. Se endpoints tiverem descrições esparsas (menos de 50 caracteres), você verá um aviso:

[mcp-openapi] WARN: Doc quality: 11 of 47 tools have sparse documentation (<50 chars)
[mcp-openapi] WARN:   Affected: getUser, createOrder, deleteItem, updateCart, listTags, ...
[mcp-openapi] WARN:   LLM accuracy may be reduced for these endpoints.

Isso ajuda a identificar quais endpoints de API podem causar baixa precisão nas chamadas de ferramentas do LLM. Suprima com --no-doc-warnings.

Filtragem de Servidores

Especificações OpenAPI podem definir múltiplos servidores (produção, staging, desenvolvimento). Selecione qual usar:

# Use first server (default behavior)
mcp-openapi --spec api.json --server 0

# Match by URL keyword
mcp-openapi --spec api.json --server prod

# Exact URL
mcp-openapi --spec api.json --server https://api.example.com/v2

Se o seletor não corresponder, você verá todos os servidores disponíveis listados.

Descoberta Dinâmica de Ferramentas

Para APIs grandes com 100+ endpoints, registrar todas as ferramentas de uma vez pode sobrecarregar o contexto do LLM. A descoberta dinâmica resolve isso registrando 3 meta-ferramentas:

Meta-ferramenta	Descrição
`search_operations(query)`	Buscar ferramentas por palavra-chave em nomes, descrições e tags
`list_by_tag(tag?)`	Navegar por ferramentas por tag OpenAPI, ou listar todas as tags
`get_tool_details(tool_name)`	Obter esquema completo de parâmetros para uma ferramenta específica

O LLM explora a API através dessas meta-ferramentas e depois chama endpoints específicos pelo nome.

# Explicit opt-in
mcp-openapi --spec large-api.json --dynamic-discovery

# Auto-enabled when spec has 100+ endpoints
mcp-openapi --spec https://api.github.com/openapi.json

Ou via arquivo de configuração:

{
  "spec": "https://api.stripe.com/openapi.json",
  "dynamicDiscovery": true,
  "auth": { "type": "bearer", "token": "$STRIPE_KEY" }
}

Recursos Pro (v0.2.0+)

O mcp-openapi inclui recursos Pro opcionais para equipes e usuários avançados, controlados por uma chave de licença.

Transformações Personalizadas de Resposta

Molde respostas de API com expressões JMESPath antes que cheguem ao LLM — reduzindo o uso de tokens e melhorando a precisão:

{
  "spec": "https://api.github.com/openapi.json",
  "licenseKey": "$MCP_OPENAPI_LICENSE_KEY",
  "transforms": {
    "list_repos": "data[].{name: name, stars: stargazers_count, url: html_url}",
    "list_*": "data[].{id: id, name: name}"
  }
}

Tratamento Inteligente de Respostas

Em vez de truncar duramente respostas grandes em 50KB, o Pro permite truncamento inteligente:

Fatiamento de arrays: Arrays grandes mostram os primeiros N itens + metadados ("showing 10 of 847 items")
Poda de profundidade: Objetos aninhados profundos são resumidos além de uma profundidade configurável
Preservação de estrutura: Você sempre vê a forma dos dados, nunca um corte no meio do JSON

{
  "spec": "./api.json",
  "licenseKey": "$MCP_OPENAPI_LICENSE_KEY",
  "response": {
    "maxLength": 50000,
    "arraySliceSize": 10,
    "maxDepth": 4
  }
}

Em Breve

Composição Multi-API — Carregar múltiplas especificações OpenAPI em uma sessão MCP
Analíticas de Uso — Rastrear chamadas de ferramentas, latência e taxas de erro

Interessado no Pro? Dê uma estrela no repositório e abra uma issue para obter acesso antecipado.

Uso Programático

Você também pode usar o mcp-openapi como biblioteca no seu próprio servidor MCP:

import { createServer } from 'mcp-openapi';

const { server, tools, spec } = await createServer({
  spec: 'https://petstore3.swagger.io/api/v3/openapi.json',
  prefix: 'petstore',
  auth: {
    type: 'bearer',
    token: process.env.API_TOKEN,
  },
});

console.log(`Loaded ${tools.length} tools from ${spec.info.title}`);

Requisitos

Node.js 18 ou posterior
Uma especificação OpenAPI 3.x ou Swagger 2.0 (URL ou arquivo local)

Contribuindo

Contribuições são bem-vindas. Veja como começar:

git clone https://github.com/Docat0209/mcp-openapi.git
cd mcp-openapi
pnpm install
pnpm test
pnpm build

Antes de enviar um PR:

Adicione testes para novos recursos
Execute pnpm lint e corrija quaisquer problemas
Siga Conventional Commits para mensagens de commit

Relacionados

graphql-to-mcp — Mesma abordagem de configuração zero para APIs GraphQL

Licença

MIT

Palavras-chave

mcp, model-context-protocol, openapi, swagger, claude, ai, llm, api, tools, rest-api, ai-tools, mcp-server