swagger

swagger-mcp-server 使用基于 Swagger 文档的接口约束来让大模型通过自然语言与网站 API 进行对话和交互。服务器读取本地 Swagger/OpenAPI 文档，模型在回答问题时可以自动获取可用接口、参数和返回结构，并通过工具链发起实际接口调用以获取数据、执行分析或完成处理任务。主要能力包括查看接口列表、按需调用具体接口、基于接口文档自动生成测试计划以及执行自动化接口测试并输出报告。要使用时，先确保 OPEN_API_URL 指向可访问的 OpenAPI JSON 文档；随后向模型提供自然语言指令，示例包含查询网站功能、调用具体接口并在调用前查询接口的详细信息等场景。示例用法包括：查看网站的可用接口、指示模型在执行创建用户等操作前先获取接口细节、以及让模型生成测试计划并进行自动化测试。

安装与运行步骤：

1. prerequisites

• Python 3.8+ 已安装
• 访问并可用的 Swagger/OpenAPI 文档地址（如 http://localhost:8080/v3/api-docs/openapi.json）
• Cherry Studio 的 uv 工具（在本示例中通过 uv 运行 main.py）

2. 取得代码

• git clone https://github.com/maohuihua123/swagger-mcp-server.git
• 进入项目目录（示例：c:/Users/Administrator/Desktop/swagger-mcp-server）

3. 安装依赖

• 根据项目要求安装 Python 及相关依赖（若有 requirements.txt，请运行： python -m pip install -r requirements.txt
• 安装 uv 工具（如果尚未安装）例如： pipx install uvx 或 按项目说明获取 uv 命令

4. 配置 MCP Server

• 使用提供的配置示例，确保 main.py 可以在指定目录下运行，并且 OPEN_API_URL 指向可访问的 OpenAPI JSON。
• 将配置中的目录路径改为你本地的实际路径。

5. 启动

• 通过命令行执行配置中的 uv 指令，例如： uv --directory c:/Users/Administrator/Desktop/swagger-mcp-server run main.py
• 确认环境变量 OPEN_API_URL 设置正确。

6. 验证

• 访问 Swagger/OpenAPI 文档地址，确保可以获取 API 列表和文档结构。
• 通过 MCP 客户端或集成环境验证基础对话流程和接口调用。

提示与常见问题：

• 确保 OPEN_API_URL 指向一个可访问的 OpenAPI JSON；若文档结构有变，需更新模型对接口的理解。
• 若接口需要认证或额外参数，请在 OPEN_API_URL 对应的文档中维护正确的安全定义；必要时在 MCP 配置中通过 env 传递鉴权信息。
• 使用前请确认本地路径与项目结构匹配，避免绝对路径错误导致脚本找不到文件。
• 为稳定测试，尽量使用稳定的 Swagger/OpenAPI 文档版本，避免文档正在变更时模型对接口定义理解混乱。