Skip to main content
Glama

mcp-swagger-schema

一个 MCP (Model Context Protocol) 服务器,用于查询 Swagger 规范中的接口 schema。

功能

  • 根据 API 路径获取请求和响应的 JSON Schema

  • 自动解析 $ref 引用

  • 支持路径参数匹配(如 /api/users/{id})

  • 内置缓存机制

Related MCP server: swagger-json-mcp

快速开始

第一步:找到你的 Swagger JSON 地址

你需要先获取项目的 Swagger/OpenAPI 规范地址,通常是类似这样的 URL:

  • https://your-api.com/v3/api-docs

第二步:配置 MCP 服务器

在你的 MCP 配置文件中(通常是 .mcp/config.json 或类似的配置),添加如下配置:

{
  "mcpServers": {
    "swagger-schema": {
      "command": "npx",
      "args": ["-y", "mcp-swagger-schema"],
      "env": {
        "SWAGGER_SPEC_URL": "替换成你的swagger地址"
      }
    }
  }
}

⚠️ 常见问题:找不到 npx 命令

如果启动失败,提示找不到 npx,按以下步骤解决:

步骤 1:打开终端,运行以下命令

which npx

你会看到类似这样的输出:

/Users/你的用户名/.nvm/versions/node/v20.0.0/bin/npx

步骤 2:复制 bin 目录路径

把上面输出的路径,去掉最后的 /npx,得到 bin 目录:

/Users/你的用户名/.nvm/versions/node/v20.0.0/bin

步骤 3:修改配置,添加 PATH

{
  "mcpServers": {
    "swagger-schema": {
      "command": "npx",
      "args": ["-y", "mcp-swagger-schema"],
      "env": {
        "SWAGGER_SPEC_URL": "替换成你的swagger地址",
        "PATH": "步骤2得到的路径:/usr/bin:/bin"
      }
    }
  }
}

例如:

{
  "mcpServers": {
    "swagger-schema": {
      "command": "npx",
      "args": ["-y", "mcp-swagger-schema"],
      "env": {
        "SWAGGER_SPEC_URL": "https://api.example.com/swagger.json",
        "PATH": "/Users/zhangsan/.nvm/versions/node/v20.0.0/bin:/usr/bin:/bin"
      }
    }
  }
}

使用方法

配置完成后,在对话中直接说:

获取 /api/users 接口的 schema

AI 会调用工具返回该接口的请求参数和响应结构。

工具参数说明

参数

必填

说明

path

✅

接口路径,如 /api/users

method

❌

HTTP 方法(get/post/put/delete),不填会自动选择

返回示例

{
  "found": true,
  "path": "/api/users",
  "method": "post",
  "summary": "创建用户",
  "request": {
    "body": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string" }
      }
    }
  },
  "response": {
    "type": "object",
    "properties": {
      "id": { "type": "integer" },
      "name": { "type": "string" }
    }
  }
}

环境变量

变量名

必填

说明

SWAGGER_SPEC_URL

✅

Swagger/OpenAPI JSON 规范的 URL

SWAGGER_CACHE_TTL_MS

❌

缓存过期时间(毫秒),默认 60000

License

MIT

Available Tools

1 tool
get_api_schemaC

根据接口路径获取 Swagger/OpenAPI 的请求和响应 schema

Inputs: path (required), method.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool, there is no possibility of ambiguity or overlap between tools. The tool has a clear, singular purpose of retrieving API schemas based on interface paths.

    Naming Consistency5/5

    The single tool name 'get_api_schema' follows a clear verb_noun pattern (get + api_schema). Since there is only one tool, consistency is inherently perfect with no deviations to assess.

    Tool Count2/5

    A single tool is too few for a server named 'mcp-swagger-schema', which suggests a broader scope related to Swagger/OpenAPI schemas. One tool feels thin and limits functionality, such as lacking operations for listing, updating, or validating schemas.

    Completeness2/5

    The tool surface is severely incomplete for the implied domain of Swagger/OpenAPI schema management. While 'get_api_schema' provides retrieval, there are obvious gaps like creating, updating, deleting, or listing schemas, which are essential for full coverage.

    Related MCP Connectors

    Related MCP Servers