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

此示例使用 bearer token 身份验证（通过 Github 个人访问令牌），并强制将工具命名策略设为“verb and path”，因为 Github 的 operation id 不是有效的工具名称。

安装

作为 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（string）：在初始化握手期间由 MCP 服务公开的文本说明
• operation.x-mcp-tool-name（string）：自定义工具名称
• operation.x-mcp-tool-description（string）：自定义工具描述
• operation.x-mcp-tool-enabled（boolean）：启用/禁用特定操作（默认启用）

MCP 功能

目前仅支持 STDIO 传输方式。

工具

OpenAPI 规范中的操作（“端点”）会转换为 MCP 工具

• 公开所有路径/查询/JSON 正文参数（使用其 JSON schema）
• 响应按原样返回
• 默认情况下，工具名称依次通过 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 选项
• 规范中的第一个 server URL（如果是绝对 URL）
• 远程 OpenAPI 规范所在的主机
• 否则会抛出错误

例如，运行 openapi-to-mcp https://petstore3.swagger.io/api/v3/openapi.json：

• https://petstore3.swagger.io/api/v3/openapi.json 定义了一个 server，但其 URL 是相对路径（/api/v3）
• 因此会使用规范自身 URL 的主机：https://petstore3.swagger.io，并将 server 的相对路径追加到该主机后

授权

Bearer token

可以通过选项 --bearer-token 提供令牌。所有调用都会通过 Authorization: Bearer {token} 标头携带该令牌。 获取远程规范时也会提供该令牌。

OAuth2

支持 ClientCredentials、RefreshToken、Password。 如果 OpenAPI 规范为这些流程声明了 securitySchemes，则会使用相应的 tokenUrl。

如何发布

创建新的标签/版本 🤷