Which integrations are available for this server?

Provides tools for managing local caches of Swagger/OpenAPI service definitions, enabling offline search of API operations, retrieving operation details and schemas, and generating request examples.

How do I use swagger-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@swagger-mcp search datapool operations for 'well'" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

swagger-mcp

by hanzc0106

Overview Schema Source Related Servers Discussions Admin

JavaScript

Local

Swagger MCP

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

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

核心行为

MCP 工具本体可被多个项目复用。
每个业务项目拥有自己的 .swagger-mcp 配置和缓存。
查询类工具只读本地缓存，不会自动联网更新。
refresh_service 和 refresh_all_services 是仅有的远程 Swagger 拉取入口。
服务以稳定名称调用，例如 service1、service2，不需要重复提供 URL。
成功刷新后，服务配置中的 updatedAt 会记录缓存更新时间。

Related MCP server: ls-apis-mcp

架构

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

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

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

Requirements

Node.js 18 或更高版本
支持 stdio MCP 的客户端，例如 Codex

当前实现仅依赖 Node.js 内置模块。

快速开始

1. 安装 npm 包

npm install -g @hanzc0106/swagger-mcp

从源码运行和参与开发的方式见开发与测试。

从源码验证

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 -- swagger-mcp

验证注册结果：

codex mcp get swagger-local
codex mcp list

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

等价的 Codex TOML 配置如下：

[mcp_servers.swagger-local]
type = "stdio"
command = "swagger-mcp"
args = []

也可以使用 npx 启动固定版本，无需全局安装：

codex mcp add swagger-local -- npx -y @hanzc0106/swagger-mcp@0.1.0

业务项目是工具调用时的运行时上下文，而不是 Codex 全局 MCP 配置的一部分。所有项目相关 tools 都要求提供绝对路径 workspace，因此一个 MCP 注册可服务多个项目，各项目分别维护自己的 .swagger-mcp 目录。

3. 初始化业务项目

在 Agent 中调用 init_project 并提供业务项目的绝对路径。它将创建：

init_project(workspace = "<workspace>")

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

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

4. 添加并刷新服务

先添加固定的 Swagger JSON 地址：

add_service(
  workspace = "<workspace>",
  service = "service1",
  url = "https://example.com/openapi.json"
)

再明确刷新缓存：

refresh_service(workspace = "<workspace>", service = "service1")

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

search_operations(workspace = "<workspace>", service = "service1", keyword = "resource")

项目配置

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

{
  "services": {
    "service1": {
      "url": "https://example.com/openapi.json",
      "updatedAt": "2026-08-14T08:30:00.000Z"
    },
    "service2": {
      "url": "https://example.com/openapi.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

除 initialize 与 tools/list 协议请求外，以下每个 tool 都必须传入 workspace。它是业务项目的绝对路径，工具会在该路径下读写 .swagger-mcp。

项目与服务管理

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 请求示例。

当 search_operations 没有匹配项，或 get_operation、get_schema、generate_request_example 找不到所需定义时，工具会返回缓存状态和 refreshHint，而不会自动请求远程地址。

{
  "cache": {
    "hasCache": true,
    "updatedAt": "2026-08-14T08:30:00.000Z"
  },
  "refreshHint": {
    "recommended": true,
    "reason": "No cached operation matched the query.",
    "tool": "refresh_service",
    "arguments": {
      "workspace": "<workspace>",
      "service": "service1"
    }
  }
}

refreshHint 表示“本地定义可能过旧或不完整”，由 Agent 根据当前任务决定是否调用 refresh_service。它不是自动刷新机制。

常见调用

查看当前缓存状态

list_services(workspace = "<workspace>")

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

搜索接口

search_operations(
  workspace = "<workspace>",
  service = "service1",
  keyword = "resource",
  method = "GET",
  tag = "Resource",
  limit = 20
)

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

获取接口完整定义

get_operation(
  workspace = "<workspace>",
  service = "service1",
  operationId = "listResources"
)

也可以使用：

get_operation(
  workspace = "<workspace>",
  service = "service1",
  method = "GET",
  path = "/api/resources"
)

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

生成请求示例

generate_request_example(
  workspace = "<workspace>",
  service = "service1",
  operationId = "updateResource",
  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

服务使用 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 客户端注册示例
发布 GitHub Release 与 npm provenance

Available Tools

11 tools

add_serviceB

Add a named Swagger/OpenAPI source. It does not fetch the document.

Inputs: url (required), service (required), workspace (required), overwrite.

generate_request_exampleC

Generate curl, axios, or fetch code from one cached operation.

Inputs: service (required), workspace (required), path, format, +3 more.

get_operationC

Read one cached operation by operationId, or by method and path.

Inputs: service (required), workspace (required), path, method, +1 more.

get_schemaC

Read and resolve one schema from a cached Swagger/OpenAPI document.

Inputs: name (required), service (required), workspace (required).

init_projectB

Create .swagger-mcp/config.json and cache directory in the requested workspace.

Inputs: workspace (required).

list_servicesA

List configured Swagger services and local cache state. This never fetches remote documents.

Inputs: workspace (required).

refresh_all_servicesB

Explicitly refresh every configured service. This is the only bulk network operation.

Inputs: workspace (required).

refresh_serviceB

Explicitly fetch one remote Swagger/OpenAPI JSON document and overwrite only its local cache.

Inputs: service (required), workspace (required).

remove_serviceB

Remove a service from config. Existing cached document is preserved.

Inputs: service (required), workspace (required).

search_operationsB

Search operations only in the local cached document. It never fetches remote Swagger.

Inputs: service (required), workspace (required), tag, limit, +2 more.

update_serviceB

Update a service URL. It does not fetch the document.

Inputs: url (required), service (required), workspace (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

TDQS

A3.5/5.0

Scored 2026-09-11 11:00 across 11 tools

Disambiguation5/5

Each tool targets a clearly distinct action: project setup, service configuration, remote fetching, local search/retrieval, and code generation. Overlap is minimal; refresh_service and refresh_all_services differ explicitly by scope, and search_operations vs get_operation is unambiguous.

Naming Consistency5/5

All tool names follow a consistent snake_case verb_noun pattern, such as init_project, list_services, refresh_service, and get_operation. No deviations or mixed conventions are present.

Tool Count5/5

With 11 tools, the set is well-scoped for managing Swagger/OpenAPI services, covering setup, service CRUD, refresh, search, retrieval, and example generation without redundancy.

Completeness5/5

The tool surface covers the full lifecycle: project initialization, service add/update/remove/list, explicit local and bulk refresh, operation search and retrieval, schema resolution, and request example generation. No obvious gaps exist for the stated purpose.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Swagger MCP
com.smartbear
MCP server for AI access to Swagger by SmartBear.
API Testing Documentation Access Developer Tools
144
https://swagger.mcp.smartbear.com/mcp
Harshith Nayaka L portfolio docsA
io.github.HarshithNayakaL
Read-only MCP server over the developer docs for the portfolio's JSON API, MCP, A2A and NLWeb.
Documentation Access Developer Tools
31
https://harshith-nayaka-l-portfolio.vercel.app/mcp/docs
JiZhiMCPB
io.github.alanwang100
Host any HTTP API as a standard MCP server; auto-distribute to 12+ mainstream agent platforms.
Developer Tools Agent Orchestration
211
https://mcp.xn--5kvtwv52d.com/mcp/gateway
Context AwesomeA
io.github.bh-rat
MCP server for accessing curated awesome list documentation
Documentation Access Research & Data
2261
https://www.context-awesome.com/api/mcp

Related MCP Servers

OpenAPI Schema Explorer
Developer Tools
kadykov
A
license
Not graded
quality
B
maintenance
MCP server providing token-efficient access to OpenAPI/Swagger specs via MCP Resources for client-side exploration.
Updated 8 days ago (2026-11-07 02:53 UTC)
507 npm
76
MIT
ls-apis-mcp
Open Data Search
koalyptus
A
license
A
quality
B
maintenance
Public APIs Discovery for Humans & Agents
Updated a day ago (2026-11-13 23:50 UTC)
3
1
MIT
openapi-mcp
Documentation Access API Testing
ceski23
A
license
Not graded
quality
C
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.
Updated 4 months ago (2026-07-23 20:04 UTC)
20 npm
3
MIT
swagger-mcp
Documentation Access Developer Tools
emreycolakoglu
A
license
A
quality
D
maintenance
A read-only MCP server for navigating OpenAPI / Swagger specifications, enabling agents to search endpoints, retrieve parameters and schemas, and inspect authentication without loading the full spec into context.
Updated 4 months ago (2026-07-08 19:20 UTC)
9
7 npm
MIT

Swagger MCP

核心行为

架构

Requirements

快速开始

1. 安装 npm 包

从源码验证

2. 注册到 Codex

3. 初始化业务项目

4. 添加并刷新服务

项目配置

MCP Tools

项目与服务管理

缓存刷新

缓存查询

常见调用

查看当前缓存状态

搜索接口

获取接口完整定义

生成请求示例

安全与隐私

开发与测试

代码结构

当前限制

Roadmap

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

OpenAPI Schema Explorer

ls-apis-mcp

openapi-mcp

swagger-mcp