Openapi To Mcp

openapi-to-mcp

OpenAPI 仕様を使用して、API のエンドポイントを型安全なツールとして公開します。

https://petstore3.swagger.io/ の基本的な例 🎉

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

Github の 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"
            ]
        }
    }
}

この例では、ベアラートークン認証（Github の個人用アクセストークンを使用）を使い、Github の operation id は有効なツール名ではないため、ツールの命名戦略を「verb and path」に固定しています。

インストール

Nuget ツールとして：openapi-to-mcp

dotnet tool install --global openapi-to-mcp

または、リリースから実行ファイルをダウンロードしてください。

使用方法

Usage:
  openapi-to-mcp <open-api> [options]

Arguments:
  <open-api>  You OpenAPI specification (URL or file) [required]

Options:
  -t, --tool-naming-strategy <extension|extension_or_operationid_or_verbandpath|operationid|verbandpath>  How the tool name should be computed [default: extension_or_operationid_or_verbandpath]
  -h, --host-override                                                                                     Host override
  -b, --bearer-token                                                                                      Bearer token
  -o2, --oauth-2-grant-type <client_credentials|password|refresh_token>                                   OAuth2 flow to be used
  -o2_tu, --oauth-2-token-url                                                                             OAuth2 token endpoint URL (override the one defined in your OpenAPI for your chosen OAuth2 flow)
  -o2_ci, --oauth-2-client-id                                                                             OAuth2 client id (for the client_credentials grant_type)
  -o2_cs, --oauth-2-client-secret                                                                         OAuth2 client secret (for the client_credentials grant_type)
  -o2_rt, --oauth-2-refresh-token                                                                         OAuth2 refresh token (for the refresh_token grant_type)
  -o2_un, --oauth-2-username                                                                              OAuth2 username (for the password grant_type)
  -o2_pw, --oauth-2-password                                                                              OAuth2 password (for the password grant_type)
  -i, --instructions                                                                                      MCP instruction to be advertised by the server
  --verbose                                                                                               Log more info (in sdterr) [default: False]
  -?, -h, --help                                                                                          Show help and usage information
  --version                                                                                               Show version information

OpenAPI のサポート

• 現在、OpenAPI 2.0 および 3.0 がサポートされています。
  • 3.1 はサポートされていません（少なくとも microsoft/OpenAPI.NET が対応するまではサポートされません）。
• 仕様は JSON/YAML 形式で、ローカル（ファイル）またはリモート（URL）に配置できます。
• ローカルの $refs のみがサポートされています。

OpenAPI のカスタム拡張機能

API の公開方法をカスタマイズするためのカスタム拡張機能が用意されています。

• info.x-mcp-instructions（文字列）：initialize ハンドシェイク中に MCP サーバーが公開するテキスト形式の指示
• operation.x-mcp-tool-name（文字列）：カスタムツール名
• operation.x-mcp-tool-description（文字列）：カスタムツールの説明
• operation.x-mcp-tool-enabled（ブール値）：特定の operation を有効／無効にします（デフォルトでは有効）

MCP の機能

現在サポートされているトランスポートは STDIO のみです。

ツール

OpenAPI 仕様の operation（「エンドポイント」）は、MCP のツールに変換されます。

• すべてのパス／クエリ／JSON ボディのパラメーターが公開されます（JSON スキーマを使用）。
• レスポンスはそのまま返されます。
• デフォルトでは、ツール名はまず operation.x-mcp-tool-name 拡張機能、次に operation.operationId、最後に {httpMethod}_{escaped_path} を使用して算出されます。
  • ツールの命名戦略は、--tool-naming-strategy オプションで指定できます。
  • ⚠️名前が ^[a-zA-Z0-9_-]{1,64}$ に一致しないツールは破棄されます。
• ツールの説明は、次の順に取得されます：operation.x-mcp-tool-description ?? operation.description ?? path.description

ツール呼び出しとホスト

ツールが呼び出されると、MCP サーバーは対応するエンドポイントを呼び出します。呼び出すホストは、次のパラメーターを組み合わせて決定します。

• --host-override オプション
• 仕様の最初のサーバーの URL（絶対 URL の場合）
• 指定されたリモート OpenAPI のホスト
• それ以外の場合は、エラーがスローされます。

たとえば、openapi-to-mcp https://petstore3.swagger.io/api/v3/openapi.json を実行すると：

• https://petstore3.swagger.io/api/v3/openapi.json にはサーバーが定義されていますが、その URL は相対 URL（/api/v3）です。
• そのため、仕様自体の URL のホストである https://petstore3.swagger.io が使用され、サーバーの相対パスが追加されます。

認証

ベアラートークン

トークンは --bearer-token オプションで指定できます。すべての呼び出しで Authorization: Bearer {token} ヘッダーとして渡されます。 リモートの仕様を取得する際にも渡されます。

OAuth2

ClientCredentials、RefreshToken、Password がサポートされています。 OpenAPI 仕様でこれらのフローの securitySchemes が宣言されている場合、対応する tokenUrl が使用されます。

公開方法

新しいタグ／リリースを作成します 🤷