swagger-mcp

swagger-mcp

概述

swagger-mcp 是一款工具，可读取 Swagger 2.0 或 OpenAPI 3.0 规范，并在运行时动态生成 MCP 工具——每个 API 端点对应一个工具。任何 MCP 客户端都可以使用这些工具与 API 进行由大模型驱动的交互。

支持的规范格式：

• Swagger 2.0（swagger: "2.0"）——路径、查询和标头参数，以及 in: body 请求体
• OpenAPI 3.0（openapi: "3.0.x"）——路径、查询和标头参数，以及采用内联或 $ref 架构的 requestBody

从架构的 required 数组中读取必填和可选字段，并在生成的工具定义中遵循这些设置。

📽️ 演示视频

观看演示视频，了解该项目的实际运行情况：

🙌 支持

如果你认为这个项目有价值，请通过 LinkedIn 支持我：

• 👍 为我们的演示帖点赞并分享
• 💬 在评论中留下你的想法和反馈
• 🔗 与我建立联系，以便获取后续更新

你在 LinkedIn 上的支持将帮助我触达更多人并改进这个项目！

前置条件

使用 swagger-mcp 前，请确保具备以下依赖项：

1. 大模型 API 密钥／本地大模型：需要能够访问 OpenAI、Claude 或 Ollama 模型。
2. 任意 MCP 客户端：（使用了 mark3labs - mcphost）

安装与设置

go install github.com/danishjsheikh/swagger-mcp@latest

运行配置

Stdio 模式（默认）

swagger-mcp --specUrl=https://your_swagger_api_docs.json

SSE 模式

swagger-mcp --specUrl=https://your_swagger_api_docs.json --sse --sseAddr=:8080

StreamableHTTP 模式

swagger-mcp --specUrl=https://your_swagger_api_docs.json --http --httpAddr=:8080

所有标志

标志	说明
--specUrl	Swagger/OpenAPI JSON 规范的 URL 或 file:// 路径（必填）
--baseUrl	覆盖 API 请求的基础 URL
--sse	以 SSE 模式运行，而非 stdio 模式
--sseAddr	SSE 监听地址，格式为 :Port 或 IP:Port
--sseUrl	SSE 基础 URL（若未指定，则根据 --sseAddr 自动推导）
--sseHeaders	要从 SSE 转发到 API 的逗号分隔请求标头（例如 Authorization,X-Tenant）
--http	以 StreamableHTTP 模式运行，而非 stdio 模式
--httpAddr	StreamableHTTP 监听地址，格式为 :Port 或 IP:Port
--httpPath	StreamableHTTP 端点路径（默认值为 /mcp）
--httpHeaders	要从 HTTP 转发到 API 的逗号分隔请求标头
--includePaths	要包含的逗号分隔路径或正则表达式模式
--excludePaths	要排除的逗号分隔路径或正则表达式模式
--includeMethods	要包含的逗号分隔 HTTP 方法（例如 GET,POST）
--excludeMethods	要排除的逗号分隔 HTTP 方法
--security	身份验证类型：basic、bearer 或 apiKey
--basicAuth	Basic 身份验证凭据，格式为 user:password
--bearerAuth	用于 Authorization 标头的 Bearer 令牌
--apiKeyAuth	API 密钥：passAs:name=value——passAs 可以是 header、query 或 cookie；多项配置以逗号分隔（例如 header:token=abc,query:user=foo）
--headers	每个请求都要附加的静态标头，格式为 name1=value1,name2=value2

Xquik OpenAPI 示例

Xquik 为其 X/Twitter 自动化 API 发布了远程 OpenAPI 文档。 由于该 API 使用 API 密钥标头，请使用 --security=apiKey 和 --apiKeyAuth 传入密钥：

export XQUIK_API_KEY="your-xquik-api-key"

swagger-mcp \
  --specUrl=https://xquik.com/openapi.json \
  --baseUrl=https://xquik.com \
  --security=apiKey \
  --apiKeyAuth=header:x-api-key=$XQUIK_API_KEY

也可以在 MCP 客户端配置中使用相同的参数：

{
  "mcpServers": {
    "xquik": {
      "command": "swagger-mcp",
      "args": [
        "--specUrl=https://xquik.com/openapi.json",
        "--baseUrl=https://xquik.com",
        "--security=apiKey",
        "--apiKeyAuth=header:x-api-key=<XQUIK_API_KEY>"
      ]
    }
  }
}

MCP 配置

要与 mcphost 集成，请在 .mcp.json 中加入以下配置：

{
    "mcpServers": {
        "swagger_loader": {
            "command": "swagger-mcp",
            "args": ["--specUrl=<swagger/doc.json_url>"]
        }
    }
}

使用 Bearer 身份验证并筛选路径：

{
    "mcpServers": {
        "swagger_loader": {
            "command": "swagger-mcp",
            "args": [
                "--specUrl=https://api.example.com/openapi.json",
                "--security=bearer",
                "--bearerAuth=your-token-here",
                "--includeMethods=GET,POST"
            ]
        }
    }
}

请求正文支持

支持 Swagger 2.0 和 OpenAPI 3.0 请求正文：

• Swagger 2.0：parameters 中的 in: body，以及 definitions 下的 $ref 或内联架构
• OpenAPI 3.0：requestBody.content.<media-type>.schema——如果是 $ref，则从 components/schemas 解析；如果是对象架构，则直接使用内联架构

架构 required 数组中列出的字段会在 MCP 工具中标记为必填。其他所有字段均为可选；未提供时，不会包含在请求中。

演示流程

1. 某个后端：

   go install github.com/danishjsheikh/go-backend-demo@latest 
   go-backend-demo
   

2. Ollama

   ollama run llama3.2
   

3. MCP 客户端

   go install github.com/mark3labs/mcphost@latest
   mcphost -m ollama:llama3.2 --config <.mcp.json_file_path>
   

流程图

🛠️ 需要帮助

我正在努力改进工具定义，以实现以下目标：
✅ 更好地处理错误，从而提供更准确的响应
✅ 控制大模型行为，确保其仅依赖 API 响应，而不使用自身记忆
✅ 通过强制从 API 严格获取数据，防止幻觉和随机生成数据

如果你对改进这些方面有见解或建议，请通过以下方式参与贡献：

• 分享你在类似实现中的经验
• 建议修改工具定义
• 针对当前限制提供反馈

你的意见将对提升此工具的可靠性和有效性大有帮助！🚀