mcp-openapi-runner

Transforme qualquer especificação OpenAPI em ferramentas MCP acionáveis para o Claude — aponte para qualquer especificação OpenAPI 3.x e o Claude poderá chamar cada endpoint por meio de linguagem natural.

GitHub

Experimente este MCPPatrocinado

Documentação

mcp-openapi

Transforme qualquer especificação OpenAPI em ferramentas MCP para Claude — zero configuração, acesso instantâneo à API.

Aponte o mcp-openapi-runner para qualquer especificação OpenAPI 3.x e o Claude poderá chamar todos os endpoints por meio de linguagem natural. Sem código de integração personalizado. Sem definições manuais de ferramentas. Uma linha de configuração.

Por que mcp-openapi?

Sem mcp-openapi	Com mcp-openapi
Escreva um servidor MCP personalizado para cada API	Uma linha de configuração por API
Defina esquemas de ferramentas manualmente	Gerado automaticamente a partir da especificação OpenAPI
Lide com autenticação, parâmetros e corpo manualmente	Autenticação integrada + tratamento de parâmetros
Mantenha o código conforme a API evolui	Mudanças na especificação = ferramentas atualizadas automaticamente

Início rápido

Adicione à configuração MCP do seu Claude Desktop / Claude Code / Cursor / Cline:

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

É isso. O Claude agora pode descobrir e chamar todos os endpoints dessa API.

Exemplo de conversa

Você: Quais animais de estimação estão disponíveis? Adicione um novo cachorro chamado Buddy.

Claude: Deixe-me verificar o que está disponível. [chama list_endpoints → descobre findPetsByStatus, addPet, ...] [chama call_endpoint → findPetsByStatus com status=available]

Há 3 animais de estimação disponíveis atualmente. Agora vou adicionar o Buddy... [chama call_endpoint → addPet com {"name":"Buddy","status":"available"}]

Pronto! O Buddy foi adicionado com o ID 12345.

Recursos

Zero configuração — basta apontar para uma URL ou arquivo de especificação
Qualquer especificação OpenAPI 3.x — JSON ou YAML, local ou remota, $ref resolvido automaticamente
operationIds gerados automaticamente — funciona mesmo quando a especificação não os define
Autenticação integrada — Bearer, chave de API, autenticação Basic via variáveis de ambiente
Filtragem de endpoints — exponha apenas os endpoints necessários com --filter
Cabeçalhos personalizados — envie cabeçalhos arbitrários com --header
Substituição de URL do servidor — aponte para staging/local com --server-url
Design de duas ferramentas — fluxo de trabalho simples list_endpoints → call_endpoint
Funciona em qualquer lugar — Claude Desktop, Claude Code, Cursor, Cline, qualquer cliente MCP

Configurações prontas para uso

Stripe

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-runner", "--spec", "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json"],
      "env": {
        "OPENAPI_BEARER_TOKEN": "sk_test_..."
      }
    }
  }
}

API REST do GitHub

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-runner",
        "--spec", "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json",
        "--filter", "repos"],
      "env": {
        "OPENAPI_BEARER_TOKEN": "ghp_..."
      }
    }
  }
}

Sua API interna

{
  "mcpServers": {
    "internal": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-runner", "--spec", "http://localhost:8080/openapi.json"],
      "env": {
        "OPENAPI_API_KEY": "dev-key-123"
      }
    }
  }
}

Jira (Atlassian)

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-runner",
        "--spec", "https://dac-static.atlassian.com/cloud/jira/platform/swagger-v3.v3.json",
        "--server-url", "https://your-domain.atlassian.net",
        "--filter", "issue"],
      "env": {
        "OPENAPI_BASIC_USER": "you@company.com",
        "OPENAPI_BASIC_PASS": "your-api-token"
      }
    }
  }
}

Autenticação

Envie credenciais por meio de variáveis de ambiente:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-runner", "--spec", "https://api.example.com/openapi.json"],
      "env": {
        "OPENAPI_BEARER_TOKEN": "your-token-here"
      }
    }
  }
}

Variável	Descrição
`OPENAPI_BEARER_TOKEN`	Token Bearer → `Authorization: Bearer <token>`
`OPENAPI_API_KEY`	Valor da chave de API
`OPENAPI_API_KEY_HEADER`	Nome do cabeçalho para a chave de API (padrão: `X-Api-Key`)
`OPENAPI_BASIC_USER`	Nome de usuário para autenticação Basic HTTP
`OPENAPI_BASIC_PASS`	Senha para autenticação Basic HTTP

Opções de CLI

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

Options:
  --spec         Path or URL to an OpenAPI 3.x spec (JSON or YAML)
  --server-url   Override the base URL from the spec
  --filter       Only expose endpoints matching a pattern (path, tag, or operationId)
  --header       Add custom header to all requests ("Name: Value", repeatable)
  --help         Show help

Exemplos

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

# Only pet-related endpoints
npx mcp-openapi-runner --spec ./openapi.yaml --filter pets

# Point at local dev server
npx mcp-openapi-runner --spec ./openapi.yaml --server-url http://localhost:3000

# Custom headers
npx mcp-openapi-runner --spec ./openapi.yaml --header "X-Tenant: acme" --header "X-Debug: true"

# With auth
OPENAPI_BEARER_TOKEN=mytoken npx mcp-openapi-runner --spec https://api.example.com/openapi.json

Ferramentas

mcp-openapi-runner expõe exatamente duas ferramentas:

Ferramenta	Descrição
`list_endpoints`	Retorna todas as operações agrupadas por tag com operationIds, métodos, caminhos e parâmetros
`call_endpoint`	Executa qualquer operação por `operationId` com parâmetros de caminho/consulta/cabeçalho/corpo

O design de duas ferramentas garante que o Claude sempre tenha um fluxo de trabalho claro: descobrir → chamar.

Como funciona

Carrega a especificação OpenAPI da URL ou caminho de arquivo fornecido
Remove referências de todos os esquemas $ref usando @apidevtools/swagger-parser
Aplica o filtro de endpoints se --filter estiver definido
Registra duas ferramentas MCP no cliente conectado
list_endpoints gera um resumo legível para humanos e LLMs de todas as operações
call_endpoint resolve parâmetros, constrói a URL, anexa autenticação + cabeçalhos personalizados e retorna a resposta

Requisitos

Node.js 18+
Especificação OpenAPI 3.x (JSON ou YAML, arquivo local ou URL)

Contribuindo

Contribuições são bem-vindas! Consulte CONTRIBUTING.md para diretrizes.

Licença

MIT