Skip to main content
Glama
hanzc0106

swagger-mcp

by hanzc0106
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

Swagger MCP

一个独立的 stdio MCP 服务，用于在任意业务项目中维护多后端服务的 Swagger/OpenAPI 本地缓存，并提供离线接口检索能力。

后端 Swagger JSON 地址通常固定，但开发时不应每次查询接口都访问远程服务。Swagger MCP 用服务名定位文档，默认只查询本地缓存；只有明确执行刷新工具时，才会重新请求远程 Swagger JSON。

核心行为

  • MCP 工具本体可被多个项目复用。

  • 每个业务项目拥有自己的 .swagger-mcp 配置和缓存。

  • 查询类工具只读本地缓存，不会自动联网更新。

  • refresh_service 和 refresh_all_services 是仅有的远程 Swagger 拉取入口。

  • 服务以稳定名称调用，例如 datapool、timeline，不需要重复提供 URL。

  • 成功刷新后，服务配置中的 updatedAt 会记录缓存更新时间。

Related MCP server: ls-apis-mcp

架构

<installation-dir>/                       # MCP 工具本体
  bin\
  src\

<workspace>/                              # 被接入的业务项目
  .swagger-mcp\
    config.json                           # 服务名称、URL 与更新时间
    cache\
      datapool.openapi.json               # 本地 Swagger/OpenAPI 缓存
      timeline.openapi.json

swagger-mcp 不属于业务项目源码。.swagger-mcp 则是该业务项目独有的运行时状态，不同项目可以有不同的服务清单、环境地址和缓存版本。

Requirements

  • Node.js 18 或更高版本

  • 支持 stdio MCP 的客户端，例如 Codex

当前实现仅依赖 Node.js 内置模块，无需安装第三方依赖。

快速开始

1. 获取并验证工具

git clone https://github.com/hanzc0106/swagger-mcp.git <your-path>/swagger-mcp
cd <your-path>/swagger-mcp
npm test

2. 注册到 Codex

以下命令会注册一个名为 swagger-local 的全局 stdio MCP。注册只声明工具本体，不绑定任何业务项目：

codex mcp add swagger-local -- node <installation-dir>/bin/swagger-mcp.js

验证注册结果：

codex mcp get swagger-local
codex mcp list

注册后请重启 Codex 或新建任务，使客户端重新启动 MCP 并发现 tools。

等价的 Codex TOML 配置如下：

[mcp_servers.swagger-local]
type = "stdio"
command = "node"
args = [
  "<installation-dir>/bin/swagger-mcp.js"
]

业务项目是工具调用时的运行时上下文，而不是 Codex 全局 MCP 配置的一部分。一个已注册的 Swagger MCP 应可服务多个项目，各项目分别维护自己的 .swagger-mcp 目录。

3. 初始化业务项目

在 Agent 中调用 init_project。它将创建：

<workspace>/.swagger-mcp/
  config.json
  cache/

注意：如果项目根目录中已经存在名为 .swagger-mcp 的文件，它会与需要创建的同名目录冲突。请先迁移或重命名旧文件，工具不会覆盖它。

4. 添加并刷新服务

先添加固定的 Swagger JSON 地址：

add_service(
  service = "datapool",
  url = "http://example.com/datapool/swagger/v1/swagger.json"
)

再明确刷新缓存：

refresh_service(service = "datapool")

刷新成功后即可离线搜索：

search_operations(service = "datapool", keyword = "well")

项目配置

/.swagger-mcp/config.json 示例：

{
  "services": {
    "datapool": {
      "url": "http://example.com/datapool/swagger/v1/swagger.json",
      "updatedAt": "2026-08-14T08:30:00.000Z"
    },
    "timeline": {
      "url": "http://example.com/timeline/swagger/v1/swagger.json",
      "updatedAt": null
    }
  }
}

字段

含义

services

以服务名为键的 Swagger 服务集合。服务名只能包含字母、数字、下划线和连字符。

url

固定 Swagger/OpenAPI JSON 地址。支持 http、https 和本地 file URL。

updatedAt

最近一次成功写入本地缓存的 ISO 8601 时间。null 表示尚未成功刷新。

缓存文件位于：

<workspace>/.swagger-mcp/cache/<service>.openapi.json

MCP Tools

项目与服务管理

Tool

联网

说明

init_project

否

初始化当前工作区的 .swagger-mcp。

list_services

否

列出配置服务及缓存状态、缓存大小、文档信息和 updatedAt。

add_service

否

添加服务名与 Swagger JSON URL，不会自动拉取文档。

update_service

否

修改已有服务 URL，不会自动刷新。

remove_service

否

删除服务配置；已有缓存文件会保留，避免无意丢失本地快照。

缓存刷新

Tool

联网

说明

refresh_service

是

根据已保存的 URL 拉取一个服务的 Swagger JSON，校验后覆盖该服务缓存，并更新 updatedAt。

refresh_all_services

是

依次刷新全部已配置服务；单个服务失败不会阻止其他服务刷新。

刷新失败时，原有缓存会保留，updatedAt 不会更新。

缓存查询

Tool

联网

说明

search_operations

否

通过关键词、HTTP 方法、Tag 搜索本地缓存中的接口。

get_operation

否

根据 operationId，或 method 加 path 读取完整接口定义。

get_schema

否

读取并展开一个 OpenAPI schema 或 Swagger 2 definitions schema。

generate_request_example

否

为指定接口生成 curl、axios 或 fetch 请求示例。

如果未找到本地缓存，查询工具会报错并提示先执行 refresh_service，但不会自行请求远程地址。

常见调用

查看当前缓存状态

list_services()

结果会包含服务 URL、updatedAt、是否存在缓存、缓存文件位置、文档标题、OpenAPI 版本和接口数量。

搜索接口

search_operations(
  service = "datapool",
  keyword = "well",
  method = "GET",
  tag = "Well",
  limit = 20
)

keyword 会匹配路径、HTTP 方法、operationId、摘要、描述和 Tag。

获取接口完整定义

get_operation(
  service = "datapool",
  operationId = "listWells"
)

也可以使用：

get_operation(
  service = "datapool",
  method = "GET",
  path = "/api/wells"
)

返回内容包括参数、请求体、响应、鉴权配置，并解析文档内的本地 $ref。

生成请求示例

generate_request_example(
  service = "datapool",
  operationId = "updateWell",
  format = "axios",
  baseUrl = "https://api.example.com"
)

format 支持 curl、axios、fetch。若未提供 baseUrl，会使用 OpenAPI servers 第一个地址；若文档未配置服务地址，则使用 占位符。

安全与隐私

  • Swagger URL 可能是内网地址，不应提交到公开仓库。

  • OpenAPI 文档可能暴露内部接口、字段和鉴权描述，请按团队数据规则处理缓存文件。

  • 本工具只下载 Swagger/OpenAPI 文档，不会调用业务 API。

  • 不存在自动刷新或后台定时刷新，所有网络请求都由刷新工具显式触发。

  • 不要将 Token、Cookie、认证 Header 写入可提交的 config.json。

  • 建议将本地环境地址和缓存加入业务项目的 .gitignore，例如：

.swagger-mcp/cache/

是否提交 config.json 取决于服务 URL 是否敏感，以及团队是否需要共享服务清单。

开发与测试

cd <installation-dir>
npm test

测试覆盖以下主流程：

初始化工作区
  -> 添加 file URL 服务
  -> 显式刷新缓存
  -> 搜索接口
  -> 查询 schema
  -> 生成请求示例

可直接以 stdio 方式运行服务：

node <installation-dir>/bin/swagger-mcp.js --workspace <workspace>

服务使用 JSON-RPC over stdio。初始化后通过 tools/list 声明能力，并通过 tools/call 执行具体工具。

代码结构

bin/
  swagger-mcp.js       MCP 进程入口
src/
  server.js            JSON-RPC 协议、工具声明与分发
  workspace.js         工作区和 .swagger-mcp 路径解析
  config.js            config.json 初始化与服务配置读写
  cache.js             Swagger 缓存读写与显式刷新
  openapi.js           OpenAPI/Swagger 解析、$ref 展开与示例生成
tests/
  fixtures/            测试 OpenAPI 文档
  run-tests.js         端到端主流程测试

当前限制

  • 支持 JSON 格式的 OpenAPI/Swagger 文档，不支持 YAML。

  • 支持文档内部的本地 $ref，不支持跨文件或远程 $ref。

  • 不管理 Token、Cookie、认证 Header。

  • 不直接调用业务接口。

  • 不提供自动刷新、定时刷新或远程缓存同步。

Roadmap

  • 支持 OpenAPI YAML

  • 支持 ETag / Last-Modified 以优化显式刷新

  • 支持两份 Swagger 文档的接口差异比较

  • 支持本地私有认证配置

  • 增加更多 MCP 客户端注册示例

  • 发布为可安装的 npm 包

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • OpenAPI Schema Explorer

    kadykov
    A
    license
    -
    quality
    A
    maintenance
    MCP server providing token-efficient access to OpenAPI/Swagger specs via MCP Resources for client-side exploration.
    85
    76
    MIT

  • openapi-mcp

    ceski23
    A
    license
    -
    quality
    A
    maintenance
    MCP server for loading and exploring OpenAPI/Swagger specifications, enabling AI assistants to dynamically browse API contracts by loading specs, searching endpoints, inspecting schemas, and retrieving operations.
    26
    3
    MIT

View all related MCP servers

Related MCP Connectors

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/hanzc0106/swagger-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server