Swagger MCP 集成方案

让 Claude Code 直接读取和调用后端 API 接口

推荐方案：swagger-mcp (Go 版本)

为什么选择这个方案：

• Go 编译的原生二进制，性能高、资源占用低（~10-30 MB 内存）
• 支持 --baseUrl 覆盖 API 地址，完美支持本地接口
• 启动速度快（<100ms），无运行时依赖
• 支持多种认证方式（Bearer Token、Basic Auth、API Key）
• 动态生成 MCP 工具，自动解析 Swagger 规范

安装 swagger-mcp

前置条件

• Go 1.19 或更高版本

# 检查 Go 版本
go version

安装

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

# 验证
swagger-mcp --help

配置步骤

1. 在项目中创建配置文件

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "api": {
      "command": "swagger-mcp",
      "args": [
        "--specUrl=https://your-api.com/swagger.json"
      ]
    }
  }
}

2. 本地接口配置（关键）

使用 --baseUrl 覆盖 API 基础地址：

{
  "mcpServers": {
    "api": {
      "command": "swagger-mcp",
      "args": [
        "--specUrl=http://localhost:8080/swagger.json",
        "--baseUrl=http://localhost:8080"
      ]
    }
  }
}

3. 重启 Claude Code

# 在项目目录下启动
cd /path/to/your/project
claude

4. 验证 MCP 已加载

在 Claude Code 中输入：

/mcp

应该能看到 api 服务器已连接。

认证配置

参数说明

Bearer Token 认证

{
  "mcpServers": {
    "api": {
      "command": "swagger-mcp",
      "args": [
        "--specUrl=http://localhost:8080/swagger.json",
        "--baseUrl=http://localhost:8080",
        "--bearerAuth=your-bearer-token"
      ]
    }
  }
}

Basic Auth 认证

{
  "mcpServers": {
    "api": {
      "command": "swagger-mcp",
      "args": [
        "--specUrl=http://localhost:8080/swagger.json",
        "--baseUrl=http://localhost:8080",
        "--basicAuth=username:password"
      ]
    }
  }
}

API Key 认证

支持多种传递方式：header、query、cookie

{
  "mcpServers": {
    "api": {
      "command": "swagger-mcp",
      "args": [
        "--specUrl=http://localhost:8080/swagger.json",
        "--baseUrl=http://localhost:8080",
        "--apiKeyAuth=header:X-API-Key=your-api-key"
      ]
    }
  }
}

多个 API Key：

{
  "mcpServers": {
    "api": {
      "command": "swagger-mcp",
      "args": [
        "--specUrl=http://localhost:8080/swagger.json",
        "--apiKeyAuth=header:token=abc,query:user=foo,cookie:sid=xxx"
      ]
    }
  }
}

使用示例

配置完成后，可以直接在 Claude Code 中：

# 查看所有接口
列出所有可用的 API 接口

# 查询特定接口
用户登录接口怎么调用？需要传什么参数？

# 生成调用代码
帮我生成调用 /api/users 接口的 TypeScript 代码

# 分析接口设计
这个 API 的设计有什么问题？

多项目配置

每个项目单独配置，切换项目自动切换 API。

项目 A 配置

项目A/.mcp.json：

{
  "mcpServers": {
    "api": {
      "command": "swagger-mcp",
      "args": [
        "--specUrl=https://api-a.example.com/swagger.json",
        "--baseUrl=https://api-a.example.com",
        "--basicAuth=user-a:password-a"
      ]
    }
  }
}

项目 B 配置

项目B/.mcp.json：

{
  "mcpServers": {
    "api": {
      "command": "swagger-mcp",
      "args": [
        "--specUrl=https://api-b.example.com/swagger.json",
        "--baseUrl=https://api-b.example.com",
        "--bearerAuth=token-for-project-b"
      ]
    }
  }
}

配置优先级

project > user (全局)

同名 MCP 服务器，项目级会覆盖全局配置。切换项目目录后重启 Claude Code 即可自动加载对应配置。

完整配置示例

基础配置（无认证）

{
  "mcpServers": {
    "api": {
      "command": "swagger-mcp",
      "args": ["--specUrl=https://api.example.com/swagger.json"]
    }
  }
}

本地开发环境

{
  "mcpServers": {
    "api": {
      "command": "swagger-mcp",
      "args": [
        "--specUrl=http://localhost:3000/api-docs/swagger.json",
        "--baseUrl=http://localhost:3000"
      ]
    }
  }
}

生产环境 + Bearer Token

{
  "mcpServers": {
    "api": {
      "command": "swagger-mcp",
      "args": [
        "--specUrl=https://api.example.com/swagger.json",
        "--bearerAuth=your-production-token"
      ]
    }
  }
}

登录认证管理（Command + Skill）

当 API 需要先通过账号密码登录获取 token 时，使用 Command + Skill 组合管理认证流程。

目录结构

.claude/
├── commands/
│   └── api-login.md          # 登录命令
├── skills/
│   └── api-auth/
│       └── SKILL.md          # 认证逻辑
└── .api-token                # Token 缓存（不提交）

.mcp.json                     # MCP 配置

登录命令

.claude/commands/api-login.md：

---
description: 登录后端 API，获取访问令牌
---

# API 登录

## 任务
使用账号密码登录后端 API，获取 access_token。

## 步骤

1. 读取环境变量获取配置：
   - API_USERNAME
   - API_PASSWORD
   - API_BASE_URL

2. 调用登录接口：

POST ${API_BASE_URL}/api/v1/login
Content-Type: application/json

{
  "username": "${API_USERNAME}",
  "password": "${API_PASSWORD}",
  "captcha": "1111",
  "id_key": "1111"
}

3. 从响应中提取 token，保存到 `.claude/.api-token`

4. 提示登录成功，显示 token 有效期（只显示前 8 位）

## 参数
- `$1`：可选，指定用户名（覆盖环境变量）

## 注意
- Token 文件已存在且未过期时，询问是否需要重新登录
- 登录失败时显示具体错误信息
- 密码不要显示在任何输出中

认证技能

.claude/skills/api-auth/SKILL.md：

---
name: api-auth
description: 后端 API 认证流程管理
---

# API 认证管理

## 调用 API 前的认证检查

1. 检查 `.claude/.api-token` 文件是否存在
2. 如果存在，读取 token 并检查是否过期
3. 如果不存在或已过期，提示：
   "需要先登录，请运行 /api-login"

## Token 使用方式

调用 API 时添加请求头：
Authorization: Bearer <token>

## 401 错误处理

当 API 返回 401 时：
1. 提示 "Token 已过期，需要重新登录"
2. 建议运行 /api-login
3. 用户确认后重试请求

## 安全规则

- 不显示完整 token，只显示前 8 位
- 永远不显示密码
- Token 文件不提交到版本控制

更新 .gitignore

.claude/.api-token

使用流程

# 1. 首次使用，先登录
/api-login

# 2. 登录成功后，正常调用 API
查询用户列表

# 3. Token 过期时，Claude 自动提示重新登录

性能对比

常见问题

参考链接

• swagger-mcp GitHub
• Claude Code MCP 文档