OpenAPI Docs MCP

让编码 Agent 安全、准确地搜索和理解 OpenAPI / Swagger 文档。

OpenAPI Docs MCP 是一个厂商无关的 MCP Server。它读取本地或远程的 OpenAPI 文档，在内存中建立索引，让编码 Agent 能快速搜索接口并获取参数、请求体、响应和 Schema。

服务只读取接口文档，不会调用文档中描述的真实后端 API。

功能特性

• 支持 OpenAPI 3.0、3.1 和 Swagger 2.0；

• 支持 JSON、YAML、本地文件和 HTTP(S) URL；

• 支持中英文搜索，并对 Summary、Tag、Path 等字段进行确定性加权；

• 按需展开本地 $ref，限制最大深度和属性数量；

• 检测循环引用，并标记无法解析的引用；

• 兼容模式可保守修复能够明确解析的脏 $ref；

• 远程文档支持自定义请求头和超时；

• 支持运行时重新加载，失败时继续保留旧文档；

• 通过 stdio 接入任意兼容 MCP 的 Agent 或 IDE。

Related MCP server: OpenAPI MCP Bridge

快速开始

要求 Node.js 20 或更高版本。无需安装或克隆项目，直接把以下配置加入 MCP Client：

{
  "mcpServers": {
    "project-api-docs": {
      "command": "npx",
      "args": [
        "-y",
        "openapi-docs-mcp",
        "--source",
        "https://api.example.com/v3/api-docs"
      ]
    }
  }
}

不同客户端的外层字段可能是 mcpServers、servers 或其他名称，但 command 和 args 的内容相同。

读取本地文档

npx -y openapi-docs-mcp --source ./openapi.yaml

MCP Client 中使用本地文件时，建议将文档路径写成绝对路径。

读取需要鉴权的远程文档

npx -y openapi-docs-mcp \
  --source https://api.example.com/v3/api-docs \
  --header Authorization="Bearer token" \
  --header X-Tenant-Id=tenant-1 \
  --timeout 30000

同时连接多个项目

每份 OpenAPI 文档对应一个独立实例：

{
  "mcpServers": {
    "order-api-docs": {
      "command": "npx",
      "args": [
        "-y",
        "openapi-docs-mcp",
        "--source",
        "https://order.example.com/v3/api-docs"
      ]
    },
    "user-api-docs": {
      "command": "npx",
      "args": [
        "-y",
        "openapi-docs-mcp",
        "--source",
        "https://user.example.com/v3/api-docs"
      ]
    }
  }
}

各实例独立加载和刷新自己的文档，互不影响。

其他安装方式

全局安装

npm install --global openapi-docs-mcp
openapi-docs-mcp --source https://api.example.com/v3/api-docs

全局安装后的 MCP 配置：

{
  "mcpServers": {
    "project-api-docs": {
      "command": "openapi-docs-mcp",
      "args": ["--source", "https://api.example.com/v3/api-docs"]
    }
  }
}

使用 mise 固定 Node.js 版本

如果 MCP Client 使用的 Node.js 或 npx 不兼容，可以通过 mise 固定运行时：

mise exec node@24 -- npx --yes openapi-docs-mcp \
  --source https://api.example.com/v3/api-docs

对应的 MCP 配置：

{
  "mcpServers": {
    "project-api-docs": {
      "command": "mise",
      "args": [
        "exec",
        "node@24",
        "--",
        "npx",
        "--yes",
        "openapi-docs-mcp",
        "--source",
        "https://api.example.com/v3/api-docs"
      ]
    }
  }
}

如果客户端找不到 mise，可使用 Windows 的 where.exe mise 或 macOS/Linux 的 which mise 查询路径，并将 command 替换为绝对路径。

CLI 参数

MCP 工具

search_api

返回经过排序的轻量候选结果。推荐先搜索，再把结果中的 id 传给 get_api。

搜索依次侧重 summary、tags、path、description 和 operationId。中文搜索不依赖空格分词，会结合标准化、包含匹配和字符片段进行评分。

get_api

获取单个接口的完整上下文，包括 HTTP 方法、路径、参数、请求体、响应、Tags、Security、Deprecated 元数据和展开后的 Schema。

优先传入 search_api 返回的 id。如果用户已经提供精确的 path 和 method，可以直接查询；如果只提供 path，应先用 search_api 确认对应的 HTTP 方法。精确查询失败时，不应静默替换成猜测的接口。maxDepth 控制 Schema 最大展开深度，默认 5，范围为 1–12。

get_schema

按精确名称读取 components.schemas 中的 Schema。maxDepth 同样默认为 5，范围为 1–12。本地 $ref 展开具有深度、属性数量和循环引用保护。

list_groups

列出 OpenAPI Tags 及每个 Tag 下的接口数量。没有 Tag 的接口归入 untagged。

reload_document

重新加载并校验启动时指定的文档，然后原子替换内存索引。加载失败时返回错误，并继续使用上一次成功加载的文档。

推荐调用流程

用户提供精确 path + method ──────────→ get_api 直接查询
        │
        └─ 否：用简短关键词调用 search_api 搜索候选接口
        ↓
根据 summary、tag、path 选择接口
        ↓
get_api 获取请求和响应结构
        ↓
必要时调用 get_schema
        ↓
生成类型、API 方法或业务代码

文档兼容与校验

默认使用兼容校验模式。部分 Springdoc 文档会生成包含中文名称、缺少本地前缀或未转义 JSON Pointer 字符的 $ref。只要目标能够唯一确定，项目就会修复内存副本并输出诊断，但不会修改源文件。

兼容模式还会跳过无法表示为对象的 path item 或 operation，并为缺少 responses 的 operation 补充空对象。修复、跳过、未解析引用和歧义引用会通过 stderr 输出有界摘要，不会污染 MCP 使用的 stdout。

无法解析或存在多个精确候选的引用会保留原值。项目不会进行模糊、忽略大小写或裁剪空白后的匹配，也不会加载外部 URL 或文件引用。无法解析文档，或缺少顶层版本、info、paths 等整体不可用的情况，仍会阻止服务启动。

如需禁用所有兼容修复，请使用 --strict-validation。

当前限制

• 不调用真实后端 API；

• 不保存或管理后端鉴权凭证；

• 不展开其他文件或 URL 中的外部 $ref；

• 不提供向量数据库或 Embedding 搜索；

• 不支持 Streamable HTTP 部署；

• 不自动轮询 OpenAPI 文档或监听文件变化；

• 不依赖模型厂商私有能力。

文档发生变化时，可调用 reload_document，也可以重启 MCP Server。

本地开发

pnpm install
pnpm typecheck
pnpm test
pnpm build
node dist/cli.js --source ./openapi.json

本地 MCP 配置需要使用 dist/cli.js 和 OpenAPI 文档的绝对路径：

{
  "mcpServers": {
    "local-api-docs": {
      "command": "node",
      "args": [
        "C:/absolute/path/openapi-docs-mcp/dist/cli.js",
        "--source",
        "C:/absolute/path/openapi.json"
      ]
    }
  }
}

设计原则

OpenAPI / Swagger
        ↓
解析、保守归一化与校验
        ↓
标准 OpenAPI Document
        ↓
内存 Operation 索引
        ↓
Search + Formatter
        ↓
标准 MCP Tools
        ↓
任意支持 MCP 的 Agent 或 IDE

OpenAPI Document 始终是事实来源，自定义类型只用于搜索结果和 MCP 输出。Formatter 不会改写已加载的 OpenAPI 声明；兼容模式只在加载阶段修复能够唯一确定目标的局部缺陷，避免根据相似度猜测后端含义。

License

MIT