Labsco
ouvreboite logo

openapi-to-mcp

★ 33

from ouvreboite

Expose API endpoints as strongly typed tools from an OpenAPI specification. Supports OpenAPI 2.0/3.0 in JSON or YAML format, from local or remote files.

🔥🔥🔥🔥✓ VerifiedFreeQuick setup
#git#security#translation

openapi-to-mcp

Use your OpenAPI specification to expose your API's endpoints as strongly typed tools.

Basic example for https://petstore3.swagger.io/ 🎉

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

More complex example, using Github's API:

{
    "mcpServers": {
        "github": {
            "command": "openapi-to-mcp",
            "args": [
                "https://raw.githubusercontent.com/github/rest-api-description/refs/heads/main/descriptions/api.github.com/api.github.com.yaml",
                "--bearer-token",
                "github_pat_xxxxxx",
                "--tool-naming-strategy",
                "verbandpath"
            ]
        }
    }
}

This example use the bearer token auth (with a Github Personal Access Token) and force the tool naming strategy to "verb and path", as Github's operation ids are not valid tool names.

Github demo

OpenAPI support

  • Currently, OpenAPI 2.0 and 3.0 are supported.
  • Specifications can be JSON/YAML and local (file) or remote (URL)
  • Only local $refs are supported

OpenAPI custom extensions

A set of custom extensions is available to customize how your API should be exposed:

  • info.x-mcp-instructions (string): Textual instructions exposed by the MCP server during the initialize handshake
  • operation.x-mcp-tool-name (string): Custom tool name
  • operation.x-mcp-tool-description (string): Custom tool description
  • operation.x-mcp-tool-enabled (boolean): Enabled/disabled a specific operation (enabled by default)

MCP features

Only STDIO transport is currently supported.

Tools

Operations ("endpoints") from your OpenAPI specification are translated to MCP tools

  • All path/query/JSON body parameters are exposed (using their JSON schema)
  • Response is returned as-is
  • By default, the tool name is computed using first the operation.x-mcp-tool-name extension, then the operation.operationId and then {httpMethod}_{escaped_path}
    • The tool naming strategy can be defined via the --tool-naming-strategy option.
    • ⚠️Tools are discarded if their name don't match ^[a-zA-Z0-9_-]{1,64}$
  • Tools description are extracted as follows: operation.x-mcp-tool-description ?? operation.description ?? path.description

Tool call and host

When a tool is called, the MCP server will call the underlying endpoint. To determine which host to call a combination of parameters are used:

  • the --host-override option
  • your specification first server's URL if it's an absolute URL
  • the host of the remote OpenAPI provided
  • otherwise, an error is thrown

For example running openapi-to-mcp https://petstore3.swagger.io/api/v3/openapi.json:

Authorization

Bearer token

A token can be provided as option --bearer-token. It'll be provided to all calls as the Authorization: Bearer {token} header. It'll also be provided when fetching a remote specification.

OAuth2

ClientCredentials, RefreshToken, Password are supported. If your OpenAPI specification declare securitySchemes for those flows, the corresponding tokenUrl will be used.

How to publish

Create a new tag/release 🤷