使用说明

Swagger MCP

自动将Swagger/OpenAPI规范转换为MCP服务器，以便与Windsurf、Cursor或其他工具一起使用。

快速入门

swagger-mcp 用途 pipx

使用pipx从PyPI安装（推荐）：

brew install pipx
pipx ensurepath
pipx install --force swagger-mcp

或者，从源代码安装：

git clone https://github.com/context-labs/swagger-mcp.git
cd swagger-mcp
pipx install -e . --force

确认安装成功：

which swagger-mcp
which swagger-mcp-sample-server

在端口9000上的本地机器上旋转示例“产品和产品类别”API：

swagger-mcp-sample-server

访问 http://localhost:9000/docs 确认示例服务器正在运行。

我们将使用此示例服务器来演示如何在Windsurf中配置MCP服务器。

在遵循下面的Windsurf或Cursor说明之前，请确保示例服务器正在运行。

帆板运动

在Windsurf中启动MCP服务器（Windsurf设置->设置->级联->管理插件->查看原始配置）：

{
  "mcpServers": {
    "product-mcp": {
      "command": "swagger-mcp",
      "args": [
        "--spec",
        "http://localhost:9000/openapi.json",
        "--name",
        "Product-MCP",
        "--server-url",
        "http://localhost:9000"
      ]
    }
  }
}

就是这样！您的API现在可以通过Windsurf、Cursor或其他工具作为一组有利于AI的工具访问。

让你的AI代理列出、创建、更新和删除产品和类别。

光标（>=v0.46）

随着Cursor MCP集成的成熟，对Cursor的支持仍处于测试阶段。风帆冲浪是目前的首选体验。要在游标中添加自定义MCP服务器，请转到设置->游标设置->工具和集成->添加自定义MCP。

{
  "mcpServers": {
    "product mcp": {
      "command": "swagger-mcp",
      "args": [
        "--spec",
        "http://localhost:9000/openapi.json",
        "--name",
        "Product-MCP",
        "--server-url",
        "http://localhost:9000",
        "--cursor"
      ]
    }
  }
}

请注意: 在Cursor中，您可能需要替换命令 swagger-mcp 与完整的路径 swagger-mcp 可执行文件，您可以通过运行以下命令找到 which swagger-mcp.

另请注意 --cursor 旗帜。这是为了与游标兼容。

同样，从v0.46开始，MCP集成目前在Cursor中处于测试阶段，可能无法按预期工作。目前，Windsurf总体上是一种更好的体验。

VSCode

VSCode通过GitHub Copilot扩展支持MCP服务器。要使用GUI配置MCP服务器，请执行以下操作：

按 Ctrl+Shift+P （或 Cmd+Shift+P 在macOS上）打开命令面板
类型 MCP: Add Server 并选择它
按照提示配置服务器

或者，您可以手动编辑MCP配置文件：

按 Ctrl+Shift+P （或 Cmd+Shift+P 在macOS上）
类型 MCP: Open User Settings 并选择它
将服务器配置添加到JSON文件中

配置应该如下所示：

{
  "mcpServers": {
    "product-mcp": {
      "command": "swagger-mcp",
      "args": [
        "--spec",
        "http://localhost:9000/openapi.json",
        "--name",
        "Product-MCP",
        "--server-url",
        "http://localhost:9000"
      ]
    }
  }
}

备注：您可能需要替换该命令 swagger-mcp 与完整的路径 swagger-mcp 可执行文件，您可以通过运行以下命令找到 which swagger-mcp.

添加配置后，重新启动VSCode或重新加载窗口以使更改生效。

请参阅其他示例其他娱乐服务器.

附加选项

您可以传递JSON文件、YAML文件或URL --spec 选项：
- /路径/to/openapi.json
- /路径/to/openapi.yaml
- https://api.example.com/openapi.json
筛选端点：仅包括路径与正则表达式模式匹配的端点：

{
  "mcpServers": {
    "product mcp": {
      "command": "swagger-mcp",
      "args": [
        "--spec",
        "http://localhost:9000/openapi.json",
        "--name",
        "product-mcp",
        "--server-url",
        "http://localhost:9000",
        "--include-pattern",
        "category"
      ]
    }
  }
}

筛选端点：排除路径与正则表达式模式匹配的端点：

{
  "mcpServers": {
    "product mcp": {
      "command": "swagger-mcp",
      "args": [
        "--spec",
        "http://localhost:9000/openapi.json",
        "--name",
        "product-mcp",
        "--server-url",
        "http://localhost:9000",
        "--exclude-pattern",
        "product"
      ]
    }
  }
}

认证

{
  "mcpServers": {
    "product mcp": {
      "command": "swagger-mcp",
      "args": [
        "--spec",
        "http://localhost:9000/openapi.json",
        "--name",
        "product-mcp",
        "--server-url",
        "http://localhost:9000",
        "--bearer-token",
        "your-token-here",
      ]
    }
  }
}

自定义头

{
  "mcpServers": {
    "product mcp": {
      "command": "swagger-mcp",
      "args": [
        "--spec",
        "http://localhost:9000/openapi.json",
        "--name",
        "product-mcp",
        "--server-url",
        "http://localhost:9000",
        "--header",
        "X-Some-Header:your-value",
        "--header",
        "X-Some-Other-Header:your-value",
      ]
    }
  }
}

服务器URL 如果OpenAPI规范已经包含特定的服务器URL，则不必将其作为命令行参数提供。但如果你这样做，命令行 --server-url 覆盖所有端点。
恒定值

如果要始终自动为参数提供值，可以使用 --const 选项。您可以包含尽可能多的 --const 您需要的选项。

{
  "mcpServers": {
    "product mcp": {
      "command": "swagger-mcp",
      "args": [
        "--spec",
        "http://localhost:9000/openapi.json",
        "--name",
        "product-mcp",
        "--server-url",
        "http://localhost:9000",
        "--const",
        "parameter-name:your-value",
        "--const",
        "parameter-name2:your-value2"
      ]
    }
  }
}

支持的功能

所有HTTP方法（GET、POST、PUT、DELETE等）
路径参数
查询参数
文本多部分请求正文字段
JSON请求正文
承载令牌身份验证
自定义头
恒定值

局限性

尚不支持具有递归架构引用的端点。
Cursor MCP集成非常早，而且坦率地说已经失败了。我试图用光标模式来解决其中的一些问题 --cursor，但还是不太好。在Cursor MCP支持变得更好之前，您会对Windsurf更满意。
我们永远不会支持OAuth工作流的自动执行。如果OAuth工作流创建了承载令牌，您必须通过带外执行OAuth来自己获取此令牌，并将此承载令牌作为命令行参数提供。
我们不支持跨多个文件（即片段、扩展名等）的Swagger/OpenAPI规范。
我们不支持在服务器URL中替换路径变量（但我们做支持端点中的路径变量）。
一般来说，我们不支持所有Swagger/OpenAPI功能。Swagger/OpenAPI标准非常广泛，将根据需要/请求添加对更模糊功能的支持。

帮助

如果启动服务器时遇到问题，请尝试以下命令： REAL_LOGGER=true swagger-mcp-parse-dry-run ... 并提供与启动服务器时使用的所有参数相同的参数。将此信息包含在您提交的任何问题中。
如果您发现Swagger API规范不受支持，并且无法使用任何可用参数作为解决方法，请提交问题。我们将根据需要/要求为其添加支持。

命令行选项

--spec （必填）：OpenAPI/Swagger规范的路径或URL
--name （必填）：MCP服务器的名称（显示在Windsurf/Cursor中）
--server-url：API调用的基本URL（覆盖规范中定义的服务器）
--bearer-token：经过身份验证的请求的承载令牌
--additional-headers：要包含在所有请求中的附加标头的JSON字符串
--include-pattern：正则表达式模式仅包括特定的端点路径（例如，“/api/v1/.*”）
--exclude-pattern：用于排除特定端点路径的正则表达式模式（例如，“/internal/.*”）
--header：key：要包含在所有请求中的额外标头的值对。可以多次包含以指定多个标题。
--const：key：如果参数存在于端点上，则始终用于参数的常量值的值对（可以是路径变量、查询参数、顶级请求体属性或多部分非文件表单数据字段）。可以多次包含以指定多个常数值。
--auto-generate-operation-ids：为OpenAPI规范中未定义的端点自动生成操作ID。默认情况下，缺少操作ID将导致错误。当启用时从HTTP方法和路径生成ID（例如。， get_api_users_id 为了 GET /api/users/{id}).
--cursor：以光标模式运行

认证

对于需要身份验证的API：

{
  "mcpServers": {
    "product mcp": {
      "command": "swagger-mcp",
      "args": [
        "--spec",
        "http://localhost:9000/openapi.json",
        "--name",
        "product-mcp",
        "--server-url",
        "http://localhost:9000",
        "--bearer-token",
        "your-token-here",
        "--cursor"
      ]
    }
  }
}

{
  "mcpServers": {
    "product mcp": {
      "command": "swagger-mcp",
      "args": [
        "--spec",
        "http://localhost:9000/openapi.json",
        "--name",
        "product-mcp",
        "--server-url",
        "http://localhost:9000",
        "--header",
        "X-API-Key:your-key",
        "--cursor"
      ]
    }
  }
}

其他娱乐服务器

国家

{
  "mcpServers": {
    "countries": {
      "command": "swagger-mcp",
      "args": [
        "--spec",
        "https://restcountries.com/openapi/rest-countries-3.1.yml",
        "--name",
        "countries",
        "--server-url",
        "https://restcountries.com/",
        "--const",
        "fields:name"
      ]
    }
  }
}

宠物店

{
  "mcpServers": {
    "petstore": {
      "command": "swagger-mcp",
      "args": [
        "--spec",
        "https://petstore.swagger.io/v2/swagger.json",
        "--name",
        "petstore",
        "--server-url",
        "https://petstore.swagger.io/v2",
        "--header",
        "X-API-Key:special-key",
      ]
    }
  }
}

面向开发者

安装

对于开发，请使用开发依赖项进行安装：

# Clone the repository
git clone https://github.com/context-labs/swagger-mcp.git
cd swagger-mcp

# Install in development mode with dev dependencies
pip install -e ".[dev]"

要在本地计算机上进行全局安装，请使用：

bash scripts/install-global.sh

单元测试

pytest swagger_mcp/tests/unit -v

集成测试

pytest swagger_mcp/tests/integration -v --capture=no --log-cli-level=INFO

MCP检查器（用于交互式探索MCP服务器）

您必须先对最新代码进行全局安装(bash scripts/install-global.sh)，然后您可以运行检查器脚本。

您将看到服务器类型 STDIO 以及命令 swagger-mcp 预填充。

bash scripts/inspector.sh

单击“连接”，然后单击“列出工具”开始与MCP服务器交互。

日志记录

要在启用日志的情况下运行服务器，请设置 REAL_LOGGER 环境变量 true:

REAL_LOGGER=true swagger-mcp --spec http://localhost:9000/openapi.json --name product-mcp --server-url http://localhost:9000

使用说明

Swagger MCP

快速入门

帆板运动

光标（>=v0.46）

VSCode

附加选项

支持的功能

局限性

帮助

命令行选项

认证

其他娱乐服务器

国家

宠物店

面向开发者

安装

单元测试

集成测试

MCP检查器（用于交互式探索MCP服务器）

日志记录

相关 MCP

Figma MCP服务器

Markdown转换服务

MCP 协议测试服务器

图像生成服务

代码安全扫描工具

网页内容抓取服务器