-
securityA
license-
qualityAn MCP server that exposes HTTP methods defined in an OpenAPI specification as tools, enabling interaction with APIs via the Model Context Protocol.
Last updated -
8
Python
MIT License
MCP OpenAPI 模式资源管理器
MCP（模型上下文协议）服务器，通过MCP 资源提供对 OpenAPI（v3.0）和 Swagger（v2.0）规范的令牌高效访问。
项目目标
该项目的主要目标是允许 MCP 客户端（例如 Cline 或 Claude Desktop）探索大型 OpenAPI 规范的结构和细节，而无需将整个文件加载到 LLM 的上下文窗口中。它通过 MCP 资源公开规范的各个部分来实现这一点，这些资源非常适合只读数据探索。
此服务器支持从本地文件路径和远程 HTTP/HTTPS URL 加载规范。Swagger v2.0 规范在加载时会自动转换为 OpenAPI v3.0。
为什么选择 MCP 资源？
模型上下文协议定义了资源和工具。
- **资源：**表示数据源（例如文件、API 响应）。它们非常适合 MCP 客户端进行只读访问和探索（例如，在 Claude Desktop 中浏览 API 路径）。
- **工具：**表示可执行的操作或功能，通常由 LLM 用来执行任务或与外部系统交互。
虽然其他 MCP 服务器可以通过工具访问 OpenAPI 规范，但本项目专注于通过资源提供访问。这使得它对于在 MCP 客户端应用程序中直接探索特别有用。
有关 MCP 客户端及其功能的更多详细信息，请参阅MCP 客户端文档。
安装
对于推荐的使用方法（ npx和 Docker，如下所述），无需单独的安装步骤。您的 MCP 客户端将根据您提供的配置自动下载软件包或拉取 Docker 镜像。
但是，如果您更喜欢或需要明确安装服务器，则有两个选择：
- **全局安装：**您可以使用 npm 全局安装该包：请参阅下面的**方法 3，**了解如何配置 MCP 客户端以使用全局安装的服务器。
- **本地开发/安装：**您可以克隆存储库并在本地构建它：请参阅下面的**方法 4，**了解如何配置 MCP 客户端以使用
node从本地构建运行服务器。
将服务器添加到您的 MCP 客户端
此服务器设计为由 MCP 客户端（例如 Claude Desktop、Windsurf、Cline 等）运行。要使用它，您需要在客户端的设置文件（通常是 JSON 文件）中添加一个配置条目。此条目告诉客户端如何执行服务器进程（例如，使用npx 、 docker或node ）。除了客户端设置条目中指定的命令行参数外，服务器本身不需要单独的配置。
以下是将服务器条目添加到客户端配置的常用方法。
方法 1：npx（推荐）
建议使用npx ，因为它可以避免全局/本地安装并确保客户端使用最新发布的版本。
客户端配置条目示例（npx 方法）：
将以下 JSON 对象添加到 MCP 客户端配置文件的mcpServers部分。此条目指示客户端如何使用npx运行服务器：
配置说明：
- 将
"My API Spec (npx)"替换为客户端中此服务器实例的唯一名称。 - 将
<path-or-url-to-spec>替换为您指定的绝对本地文件路径或完整远程 URL。 --output-format是可选的（json，yaml，json-minified），默认为json。- 要探索多个规范，请在
mcpServers中添加单独的条目，每个条目都有唯一的名称并指向不同的规范。
方法二：Docker
您可以指示您的 MCP 客户端使用官方 Docker 镜像运行服务器： kadykov/mcp-openapi-schema-explorer 。
客户端配置条目示例（Docker 方法）：
将以下 JSON 对象之一添加到 MCP 客户端配置文件的mcpServers部分。这些条目指示客户端如何使用docker run运行服务器：
- **远程 URL：**将 URL 直接传递给
docker run。 - 使用远程 URL：
- **使用本地文件：（**需要将文件挂载到容器中）**重要提示：**请将
/full/host/path/to/spec.yaml替换为主机上正确的绝对路径。路径/spec/api.yaml是容器内的对应路径。
方法 3：全局安装（不太常见）
如果您已经使用npm install -g全局安装了该包，则可以配置您的客户端以直接运行它。
客户端配置条目示例（全局安装方法）：
将以下条目添加到 MCP 客户端的配置文件中。此操作假设mcp-openapi-schema-explorer命令可在客户端的执行环境变量 PATH 中访问。
- 确保
command（mcp-openapi-schema-explorer）可在 MCP 客户端使用的 PATH 环境变量中访问。
方法四：本地开发/安装
如果您已在本地克隆存储库以进行开发或运行修改后的版本，则此方法很有用。
设置步骤（在终端运行一次）：
- 克隆存储库：
git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git - 导航到目录：
cd mcp-openapi-schema-explorer - 安装依赖项：
npm install - 构建项目：
npm run build（或者just build）
客户端配置条目示例（本地开发方法）：
将以下条目添加到 MCP 客户端的配置文件中。这将指示客户端使用node运行本地构建的服务器。
**重要提示：**将/full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.js替换为克隆存储库中构建的index.js文件的正确绝对路径。
特征
- **MCP 资源访问：**通过直观的 URI（
openapi://info、openapi://paths/...``openapi://components/...）探索 OpenAPI 规范。 - **OpenAPI v3.0 和 Swagger v2.0 支持：**加载两种格式，自动将 v2.0 转换为 v3.0。
- **本地和远程文件：**从本地文件路径或 HTTP/HTTPS URL 加载规范。
- **令牌高效：**旨在通过提供结构化访问来最大限度地减少 LLM 的令牌使用。
- **多种输出格式：**以 JSON（默认）、YAML 或最小化 JSON（
--output-format）获取详细视图。 - 动态服务器名称： MCP 客户端中的服务器名称反映了已加载规范的
info.title。 - **引用转换：**内部
$ref(#/components/...) 转换为可点击的 MCP URI。
可用的 MCP 资源
该服务器公开以下 MCP 资源模板，用于探索 OpenAPI 规范。
了解多值参数 ( * )
一些资源模板包含以星号 ( * ) 结尾的参数，例如{method*}或{name*} 。这表示该参数接受多个逗号分隔的值。例如，要请求路径的GET和POST方法的详细信息，可以使用类似openapi://paths/users/get,post URI。这样可以在单个请求中获取多个项目的详细信息。
资源模板：
openapi://{field}- **描述：**访问 OpenAPI 文档的顶级字段（例如，
info、servers、tags），或列出paths或components的内容。具体可用字段取决于加载的规范。 - 例如：
openapi://info - 输出：
paths和components的text/plain列表；其他字段的配置格式（JSON/YAML/最小化 JSON）。 - **完成：**根据加载的规范中找到的实际顶级键为
{field}提供动态建议。
- **描述：**访问 OpenAPI 文档的顶级字段（例如，
openapi://paths/{path}- **描述：**列出特定 API 路径可用的 HTTP 方法（操作）。
- 参数：
{path}- API 路径字符串。必须进行 URL 编码（例如，/users/{id}变为users/{id}）。 - 例如：
openapi://paths/users/{id} - 输出：
text/plain方法列表。 - **完成：**根据加载的规范（URL 编码）中找到的路径，为
{path}提供动态建议。
openapi://paths/{path}/{method*}- **描述：**获取特定 API 路径上的一个或多个操作（HTTP 方法）的详细规范。
- 参数：
{path}- API 路径字符串。必须经过 URL 编码。{method*}- 一个或多个 HTTP 方法 (例如get、post、get,post)。不区分大小写。
- 示例（单个）：
openapi://paths/users/{id}/get - 示例（多个）：
openapi://paths/users/{id}/get,post - **输出：**配置格式（JSON/YAML/最小化 JSON）。
- **补全：**为
{path}提供动态建议。为{method*}提供静态建议（常见的 HTTP 动词，如 GET、POST、PUT、DELETE 等）。
openapi://components/{type}- **描述：**列出特定类型（例如，
schemas、responses、parameters）的所有已定义组件的名称。具体可用的类型取决于加载的规范。此外，还提供了每种列出类型的简短描述。 - 例如：
openapi://components/schemas - **输出：**带有描述的组件名称的
text/plain列表。 - **完成：**根据在加载的规范中找到的组件类型为
{type}提供动态建议。
- **描述：**列出特定类型（例如，
openapi://components/{type}/{name*}- **描述：**获取特定类型的一个或多个命名组件的详细规范。
- 参数：
{type}- 组件类型。{name*}- 一个或多个组件名称（例如，User、Order、User,Order）。区分大小写。
- 示例（单个）：
openapi://components/schemas/User - 示例（多个）：
openapi://components/schemas/User,Order - **输出：**配置格式（JSON/YAML/最小化 JSON）。
- **补全：**提供针对
{type}的动态建议。仅当加载的规范整体上只包含一种组件类型（例如，仅包含schemas）时，才会提供针对{name*}的动态建议。存在此限制是因为 MCP SDK 目前不支持提供针对所选{type}范围的补全；提供所有类型的所有名称可能会产生误导。
贡献
欢迎贡献代码！请参阅CONTRIBUTING.md文件，了解如何设置开发环境、运行测试以及提交更改。
发布
该项目使用semantic-release进行基于Conventional Commits 的自动化版本管理和包发布。
未来计划
（未来计划待定）
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
MCP 服务器通过 MCP 资源提供对 OpenAPI/Swagger 规范的令牌高效访问，以供客户端探索。
Related MCP Servers
- -securityAlicense-qualityA server that enables interaction with any API that has a Swagger/OpenAPI specification through Model Context Protocol (MCP), automatically generating tools from API endpoints and supporting multiple authentication methods.Last updated -1494TypeScriptApache 2.0
- AsecurityAlicenseAqualityAn MCP server that connects to a Swagger specification and helps an AI to build all the required models to generate a MCP server for that service.Last updated -51455TypeScriptMIT License
- AsecurityAlicenseAqualityA tool that creates MCP (Model Context Protocol) servers from OpenAPI/Swagger specifications, enabling AI assistants to interact with your APIs.Last updated -32121TypeScriptMIT License