openapi-mcp-server

你是否曾经尝试让 AI 帮你调用一个不熟悉的 API，结果发现它编造了错误的参数名、路径，或者遗漏了必需的认证信息？OpenAPI 规范正旨在解决这个问题，它用标准化的格式描述了 API 的每一个细节。然而，OpenAPI 文件通常非常庞大和复杂，不适合直接塞给一个语言模型。

这就是 openapi-mcp-server 要解决的问题。它是一个基于模型上下文协议的服务器，通过连接位于 oapis.org 的服务，将复杂的 OpenAPI 规范转化为简洁、易懂的“简单语言”摘要，让 AI 能够像人类阅读文档一样，准确地理解和使用任意 OpenAPI。

项目基本信息

一、项目介绍

openapi-mcp-server 是一个 MCP 服务器，它让 AI 助手能够智能地探索和使用遵循 OpenAPI 规范的 REST API。它的核心是一个三步流程：

1. 识别：根据用户的需求，确定所需的 OpenAPI 标识（例如，GitHub API、Stripe API）。
2. 概览：请求该 API 的“简单语言”摘要，让 AI 理解 API 的整体功能、认证方式和可用资源。
3. 深入：当 AI 需要调用具体端点时，它进一步获取该端点的详细说明（请求方法、路径、参数、请求体示例）。

这个项目利用了 oapis.org 服务（以及其背后的 openapisearch 和 oapis 库）来预处理 OpenAPI 文件，将技术性的 JSON/YAML 转换为 AI 更容易理解的叙述性文本。服务器本身使用 TypeScript 编写，可以部署为 Cloudflare Worker 或本地运行。

二、核心优势

将复杂的 OpenAPI 转化为 AI 友好的格式
与直接“投喂”几百 KB 的原始 OpenAPI JSON 不同，这个服务器只传递 AI “需要知道”的信息：概览、端点、参数，并且是用简单的英文描述的。

减少 AI 的“幻觉”
当 AI 能够基于真实的 API 文档（而非训练数据中的记忆）生成请求时，参数名错误、路径拼写错误、方法使用不当的概率会大大降低。

支持任何 OpenAPI
只要一个 API 提供了符合规范的 OpenAPI 文件，这个服务器就能够处理它。这意味着它可以覆盖数以万计的公共和私有 API。

即开即用的托管版本
项目提供了一个 MCP URL：https://openapi-mcp.openapisearch.com/mcp，可以直接用于支持远程 MCP 的客户端，无需本地安装和配置。

高活跃度与社区认可
该项目在 GitHub 上有近 900 颗星，并引发了 Hacker News 上的热烈讨论。这说明它解决了一个真实的痛点，并得到了社区的广泛认可。

三、适用场景

让 AI 助手调用 GitHub API
你可以问：“列出我 GitHub 账号下的所有仓库，并显示星标数量。” AI 会通过服务器了解 GitHub API 的结构，并生成正确的 API 请求。

探索不熟悉的 API
当你想使用一个新的第三方服务（比如 Airtable、Notion 或 Stripe）的 API 时，可以让 AI 先帮你“解读”其 OpenAPI 规范，总结出资源和主要操作。

自动化 API 测试
在 CI 流程中，你可以让 AI 基于 OpenAPI 规范生成一组简单的测试用例，验证 API 端点是否正常工作。

学习 API 设计
通过让 AI 分析不同服务的 OpenAPI 规范，你可以快速理解它们的资源设计模式和命名习惯。

私有 API 的内部助手
公司内部的微服务如果提供了 OpenAPI 文档，开发者可以直接在 Cursor 或 Claude 中询问：“用户服务中，按邮箱查找用户的端点是什么？”

四、安装教程

openapi-mcp-server 提供了两种使用方式：使用官方的远程服务器，或者本地运行。绝大多数情况推荐使用远程服务器，无需安装。

方法一：使用远程 MCP 服务器（推荐）

对于支持远程 MCP 的客户端（如 Claude Desktop 最新版、Cursor 等），你不需要克隆任何代码。

对于 Claude Desktop，编辑配置文件（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json；Windows: %AppData%\Claude\claude_desktop_config.json），添加以下内容：

{
  "mcpServers": {
    "openapi-explorer": {
      "url": "https://openapi-mcp.openapisearch.com/mcp"
    }
  }
}

对于 Cursor，在 MCP Servers 设置中，添加一个新的服务器，类型选择 url，然后填入上述 URL。

保存后重启客户端即可使用。

方法二：本地运行（用于开发或调试）

如果你想修改服务器代码，或者需要离线使用，可以本地运行。

第一步：克隆仓库

git clone https://github.com/janwilmake/openapi-mcp-server.git
cd openapi-mcp-server

第二步：安装依赖

项目使用 wrangler（Cloudflare Workers 的开发工具）。确保你已安装 Node.js，然后执行：

npm install

第三步：启动本地服务器

npx wrangler dev

服务器将在本地端口（通常是 localhost:8787）上运行。

第四步：使用 MCP Inspector 测试（可选）

npx @modelcontextprotocol/inspector

然后在 Inspector 中指向你本地运行的服务器。

对于客户端配置，如果你要连接本地服务器，请将上述远程 URL 替换为 http://localhost:8787/mcp。

五、使用示例

以下是在配置好远程服务器后，与 Claude Desktop 的对话示例。

示例1：获取 API 概览

用户输入：我想了解 GitHub API 的基本情况，它主要提供哪些资源？

Claude 会通过服务器获取 GitHub API 的 OpenAPI 摘要，然后回答：“GitHub API 主要围绕仓库、用户、议题拉取请求和组织等资源。认证方式推荐使用个人访问令牌。例如，你可以通过 /user/repos 获取当前用户的仓库列表。”

示例2：查询具体端点

用户输入：GitHub API 中，如何获取某个公开仓库的 readme 文件内容？

Claude 会深入查找相关端点，然后回答：“要获取 readme，应该使用 GET /repos/{owner}/{repo}/readme 端点。你需要提供仓库所有者和仓库名。你可以指定 accept 头来获取不同的媒体格式，如 application/vnd.github.v3.html 会返回 HTML 渲染后的版本。”

示例3：生成调用代码

用户输入：基于 OpenAI 的 API，生成一个 Python 代码片段，调用对话补全端点。

Claude 会从 OpenAPI 规范中提取出 /v1/chat/completions 端点的详细信息，然后生成一个带有正确参数名 model、messages 的 requests.post 调用示例。

示例4：对比两个类似 API

用户输入：对比一下 Slack API 和 Discord API 在“发送消息”这个操作上的差异。

AI 会分别查询两个服务的 OpenAPI 规范，然后总结出端点路径、参数（如 channel vs channel_id）和认证方式的不同。

六、常见问题

问题1：远程服务器提示“无法连接到 MCP 端点”。

解决方案：请检查你的网络连接，确保可以访问 openapi-mcp.openapisearch.com。由于该项目部署在 Cloudflare Workers 上，全球访问速度通常很快，但极少数网络环境可能被屏蔽。你可以尝试切换网络，或使用本地服务器方式。

问题2：AI 查询某个 API 时，提示“找不到该 API 的 OpenAPI 规范”。

解决方案：该项目依赖于后端 oapis.org 的索引。如果该 API 的 OpenAPI 文件没有公开或未被收录，服务器将无法处理。你可以尝试提供 OpenAPI 文件的 URL，或者自行使用 openapisearch 工具生成摘要。

问题3：这个服务器与直接提供 OpenAPI JSON 有什么不同？

解决方案：最大的不同在于抽象层级。原始 OpenAPI JSON 充满了技术细节（如 JSON schema、重复的嵌套结构），而此服务器提炼出了 AI 最关心的“语言”：这个 API 做什么？认证方式？有哪些端点？每个端点的参数和示例。这就像是把一部法律条文变成了通俗的说明书。

问题4：我能够为我的私有 API 运行自己的实例吗？

解决方案：可以。你可以克隆此仓库，修改后端指向你自己的 OpenAPI 存储服务（或直接使用本地文件）。但需要注意的是，该项目默认依赖 oapis.org 服务来生成“简单语言”。如果你想完全自托管，可能需要复现 openapisearch 和 oapis 的能力。

问题5：这个服务器需要 API 密钥吗？

解决方案：不需要。服务器本身是开放的。但是，当你通过 AI 调用具体的第三方 API（如 GitHub、Slack）时，你仍然需要为那些服务提供相应的认证凭证。这个 MCP 服务器只负责“理解和解释” API，不负责代表你实际调用它们。

七、总结

openapi-mcp-server 是 MCP 生态中一个极具创新性和实用价值的项目。它巧妙地利用“简单语言”中间层，解决了 LLM 与结构化 API 描述之间的“语义鸿沟”。

它的主要价值体现在：

• 通用性：理论上可以为任何符合 OpenAPI 规范的 API 提供“AI 解读”服务。
• 效率：让 AI 瞬间从“猜测 API 用法”进化到“阅读官方文档后使用”。
• 社区认可：近 900 颗星和活跃的迭代证明了它解决了一个真实、普遍的痛点。

对于任何需要与 REST API 打交道的 AI 应用开发者、希望提升 AI Agent 可靠性的工程师，或者只是想让 Claude 帮你生成更准确的 API 调用代码的用户，这个项目都值得你立即尝试。它的远程服务器方式意味着你可以在 1 分钟内体验到它的魔力。