Apifox MCP 服务器

让 AI 助手自动管理你的 Apifox API 文档！

这是一个 Model Context Protocol (MCP) 服务器，允许 Claude Desktop、Claude Code、Cursor 等 MCP 客户端通过 Apifox Open API 自动导入 OpenAPI/Swagger 规范到你的 Apifox 项目。

✨ 主要功能

• ✅ API 导入：批量导入 OpenAPI/Swagger 规范到 Apifox（稳定可靠）
• ✅ API 导出：支持 Summary（目录结构）和 Full（完整规范）两种模式
• ✅ 智能废弃标记：自动检测并标记已删除的接口为废弃状态（v1.2.1）
• ✅ 部分模块导入：支持只导入部分模块，不影响其他模块（智能范围检测）
• ✅ 多格式支持：支持 OpenAPI 3.0/3.1 和 Swagger 2.0
• ✅ 详细统计：完整的导入/导出统计信息和错误报告

🚀 快速开始

1. 安装

方式 1: 使用 npx（推荐）

无需安装，直接使用最新版本：

npx -y apifox-openapi-mcp@latest --token "YOUR_TOKEN" --project-id "YOUR_PROJECT_ID"

方式 2: 本地安装

# 克隆仓库
git clone https://github.com/yourusername/apifox-mcp.git
cd apifox-mcp

# 安装依赖
npm install

# 构建
npm run build

# 本地链接（可选，用于全局使用）
npm link

2. 获取 API Token 和项目 ID

步骤：

1. 获取 Token：登录 Apifox → 头像 → 账号设置 → API 访问令牌 → 新建令牌
2. 获取 Project ID：打开项目 → 项目设置 → 基本设置 → 复制项目 ID

3. 配置 MCP 客户端

3.1 Claude Desktop

编辑 Claude Desktop 配置文件：

• Linux/Mac: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

方式 1: 使用 npx（推荐，总是使用最新版本）

{
  "mcpServers": {
    "apifox": {
      "command": "npx",
      "args": [
        "-y",
        "apifox-openapi-mcp@latest",
        "--token",
        "你的-APIFOX-TOKEN",
        "--project-id",
        "你的-项目-ID"
      ]
    }
  }
}

方式 2: 本地安装（使用绝对路径）

{
  "mcpServers": {
    "apifox": {
      "command": "node",
      "args": [
        "/绝对路径/apifox-mcp/dist/index.js",
        "--token",
        "你的-APIFOX-TOKEN",
        "--project-id",
        "你的-项目-ID"
      ]
    }
  }
}

方式 3: 使用 npm link 后

{
  "mcpServers": {
    "apifox": {
      "command": "apifox-mcp",
      "args": [
        "--token",
        "你的-APIFOX-TOKEN",
        "--project-id",
        "你的-项目-ID"
      ]
    }
  }
}

3.2 Claude Code

方式 1: 使用 CLI 命令（推荐）

# 添加 MCP 服务器
claude mcp add apifox

# 按提示输入配置
# Command: npx
# Args: -y apifox-openapi-mcp@latest --token "你的-TOKEN" --project-id "你的-项目-ID"

# 验证配置
claude mcp list

方式 2: 直接编辑配置文件

编辑 ~/.config/Claude/claude_desktop_config.json（与 Claude Desktop 共享配置文件）：

{
  "mcpServers": {
    "apifox": {
      "command": "npx",
      "args": [
        "-y",
        "apifox-openapi-mcp@latest",
        "--token",
        "你的-APIFOX-TOKEN",
        "--project-id",
        "你的-项目-ID"
      ]
    }
  }
}

重启 Claude Code 后生效。

3.3 Cursor

步骤：

1. 打开 Cursor 设置：Cursor Settings > Features > MCP
2. 点击 + Add New MCP Server 按钮
3. 填写配置信息：
   • Name: apifox
   • Command: npx
   • Args:

     -y
     apifox-openapi-mcp@latest
     --token
     你的-APIFOX-TOKEN
     --project-id
     你的-项目-ID
     

   • Transport: stdio
4. 保存配置

使用提示：

• Cursor 的 Composer Agent 会自动使用 MCP 工具
• 最多支持 40 个 MCP 工具
• 给出明确指令时效果最佳，例如："请使用 Apifox 工具导入这个 API"

4. 重启客户端

完全退出并重新打开对应的 MCP 客户端（Claude Desktop / Claude Code / Cursor），MCP 服务器会自动加载。

📌 版本管理说明

为什么使用 @latest？

• ✅ 总是使用最新版本 - 自动获取最新功能和修复
• ✅ 无需手动更新 - npx 会自动下载最新版本
• ✅ 避免缓存问题 - 配合 -y 参数跳过确认

查看当前版本：

# 查看 npx 使用的版本
npx -y apifox-openapi-mcp@latest --version

# 查看 npm 上的最新版本
npm view apifox-openapi-mcp version

# 查看全局安装的版本
npm list -g apifox-openapi-mcp

其他版本管理方式：

1. 指定具体版本（适合生产环境）：

   "args": ["-y", "apifox-openapi-mcp@1.3.1", ...]
   

2. 全局安装（更快的启动速度）：

   npm install -g apifox-openapi-mcp
   

   然后在配置中使用 "command": "apifox-mcp"

📖 使用方法

在 MCP 客户端中使用

与 AI 助手（Claude Desktop / Claude Code / Cursor）对话，它会自动调用 MCP 工具：

你: 帮我创建一个用户管理 API 并导入到 Apifox

Claude: 好的，我为你创建一个用户管理 API...
[自动生成 OpenAPI 规范]
[自动调用 import_openapi 工具]

✅ OpenAPI 规范导入完成！

📋 接口导入统计：
  - 创建: 4
  - 更新: 0
  - 失败: 0
  - 忽略: 0

🎉 成功导入 4 个项！

🔧 可用工具

1. import_openapi - API 导入（推荐）

使用 Apifox Open API 批量导入 OpenAPI/Swagger 规范。稳定可靠，推荐使用。

参数：

• spec (必需): OpenAPI/Swagger 规范对象（必须包含 openapi/swagger、info、paths 字段）
• options (可选): 导入选项
  • endpointOverwriteBehavior: 接口覆盖行为
    • OVERWRITE_EXISTING (默认): 覆盖现有接口
    • AUTO_MERGE: 自动合并
    • KEEP_EXISTING: 保留现有
    • CREATE_NEW: 创建新接口
  • schemaOverwriteBehavior: 数据模型覆盖行为（同上）
  • markDeprecatedEndpoints: 自动标记废弃接口（v1.2.1 新增）
    • true: 启用智能废弃标记（强烈推荐）
    • false: 不标记（默认）
    • 工作原理：
      1. 导出现有接口
      2. 智能检测导入范围（如只导入 /api/marketing 模块）
      3. 只对比该范围内的接口
      4. 标记已删除的接口为 deprecated
    • 支持部分模块导入，不会误标记其他模块
  • updateFolderOfChangedEndpoint: 是否更新修改接口的目录（默认：false）
  • prependBasePath: 是否添加 basePath 前缀到路径（默认：false）
  • targetBranchId: 目标分支 ID（可选，用于多分支项目）

示例 1：基础导入

{
  "spec": {
    "openapi": "3.0.0",
    "info": {
      "title": "用户管理 API",
      "version": "1.0.0"
    },
    "paths": {
      "/users": {
        "get": {
          "summary": "获取用户列表",
          "tags": ["用户管理"],
          "responses": {
            "200": {
              "description": "成功"
            }
          }
        }
      }
    }
  },
  "options": {
    "endpointOverwriteBehavior": "OVERWRITE_EXISTING"
  }
}

示例 2：启用智能废弃标记（推荐）

{
  "spec": {
    "openapi": "3.0.0",
    "info": {
      "title": "营销模块 API",
      "version": "2.0.0"
    },
    "paths": {
      "/api/marketing/campaigns": {
        "get": {
          "summary": "获取营销活动列表",
          "tags": ["营销活动"],
          "responses": {
            "200": {
              "description": "成功"
            }
          }
        }
      }
    }
  },
  "options": {
    "endpointOverwriteBehavior": "OVERWRITE_EXISTING",
    "markDeprecatedEndpoints": true
  }
}

说明：

• 导入时会自动检测范围为 /api/marketing
• 只标记该范围内已删除的接口为废弃
• 不会影响 /api/users、/api/products 等其他模块

返回结果：

✅ OpenAPI 规范导入完成！

📋 接口导入统计：
  - 创建: 4
  - 更新: 0
  - 失败: 0
  - 忽略: 0

📦 数据模型导入统计：
  - 创建: 2
  - 更新: 0
  - 失败: 0
  - 忽略: 0

🎉 成功导入 6 个项！

2. export_openapi - API 导出

从 Apifox 项目导出 OpenAPI/Swagger 规范。AI 可以使用此工具查看现有接口，避免重复创建或参考现有风格。

参数：

• mode (可选): 导出模式
  • summary: 仅导出目录结构和接口列表（推荐，节省上下文）
  • full: 导出完整的 OpenAPI 规范（默认）
• oasVersion (可选): OpenAPI/Swagger 版本（仅 full 模式有效）
  • 2.0: Swagger 2.0
  • 3.0: OpenAPI 3.0（默认）
  • 3.1: OpenAPI 3.1
• exportFormat (可选): 导出格式（仅 full 模式有效）
  • JSON: JSON 格式（默认）
  • YAML: YAML 格式
• pathFilter (可选): 路径过滤器，只导出匹配的接口路径（支持前缀匹配）
  • 示例："/api/user" 只导出用户相关接口

示例 1：Summary 模式（推荐）

{
  "mode": "summary"
}

返回结果：

✅ 接口文档概览（Summary 模式）

📊 统计信息：
  - 项目标题: 我的 API 项目
  - 总接口数: 26

📁 目录结构和接口列表：

📂 用户管理
  └─ [GET] /api/users
     获取用户列表
  └─ [POST] /api/users
     创建用户

📂 商品管理
  └─ [GET] /api/products
     获取商品列表

💡 提示：
  - 导入新接口时，请参考上述目录结构
  - 将相关接口放入对应的目录（使用 tags 字段）

示例 2：Full 模式 + 路径过滤

{
  "mode": "full",
  "oasVersion": "3.0",
  "exportFormat": "JSON",
  "pathFilter": "/api/user"
}

返回结果：

✅ OpenAPI 规范导出成功（Full 模式）

📊 导出统计：
  - OpenAPI 版本: 3.0.1
  - 项目标题: 我的 API 项目
  - 接口数量: 2（已按 pathFilter 过滤）
  - 数据模型数量: 1

📋 接口列表：
  - /api/user [GET, POST]
  - /api/user/{id} [GET, PUT, DELETE]

📄 完整 OpenAPI 规范：
{
  "openapi": "3.0.1",
  "info": {
    "title": "我的 API 项目",
    "version": "1.0.0"
  },
  "paths": {
    "/api/user": {...},
    "/api/user/{id}": {...}
  },
  "components": {
    "schemas": {
      "User": {...}
    }
  }
}

💡 使用场景

场景 1：首次创建 API 文档

你: 帮我创建一个用户管理 API，包括 CRUD 操作

AI: [生成 OpenAPI 规范]
    [调用 import_openapi]

✅ 成功创建 4 个接口

场景 2：更新部分模块 + 自动标记废弃接口

你: 更新营销模块 API，移除优惠券接口，改用积分系统

AI: [先调用 export_openapi mode=summary 查看现有结构]
    [生成新的营销模块规范]
    [调用 import_openapi 并启用 markDeprecatedEndpoints]

🔍 检测到导入范围: /api/marketing
🔖 标记了 1 个废弃接口路径（优惠券相关）
✅ 其他模块（用户、商品）保持不变

场景 3：查看现有接口避免重复

你: 帮我添加商品搜索功能

AI: [先调用 export_openapi mode=summary]
    发现项目中已有 /api/products/search 接口
    我可以参考现有的接口风格来设计新功能...

📊 API 响应格式

导入成功后会返回详细的统计信息：

{
  "data": {
    "counters": {
      "endpointCreated": 4,       // 创建的接口数
      "endpointUpdated": 0,       // 更新的接口数
      "endpointFailed": 0,        // 失败的接口数
      "endpointIgnored": 0,       // 忽略的接口数
      "schemaCreated": 2,         // 创建的数据模型数
      "schemaUpdated": 0,         // 更新的数据模型数
      "schemaFailed": 0,          // 失败的数据模型数
      "schemaIgnored": 0          // 忽略的数据模型数
      // ... 其他计数
    },
    "errors": []  // 错误信息（如果有）
  }
}

⚙️ 命令行使用

你也可以直接从命令行运行 MCP 服务器：

# 方式 1: 使用命令行参数
node dist/index.js --token "YOUR_TOKEN" --project-id "YOUR_PROJECT_ID"

# 方式 2: 使用环境变量
export APIFOX_TOKEN="YOUR_TOKEN"
export APIFOX_PROJECT_ID="YOUR_PROJECT_ID"
node dist/index.js

# 可选参数
node dist/index.js \
  --token "YOUR_TOKEN" \
  --project-id "YOUR_PROJECT_ID" \
  --base-url "https://api.apifox.com"

🛠 技术栈

• TypeScript - 类型安全的开发
• MCP SDK - Model Context Protocol 实现
• Apifox Open API - 官方 API 接口
• Axios - HTTP 客户端

🔗 关于 Apifox Open API

本项目使用 Apifox Open API 官方接口，经过充分测试，以下功能稳定可用：

| 功能 | API 端点 | 状态 | 说明 | |-----|---------|------|------| | 导入 OpenAPI | POST /v1/projects/{projectId}/import-openapi | ✅ 稳定 | 支持批量导入、覆盖策略、废弃标记 | | 导出 OpenAPI | POST /v1/projects/{projectId}/export-openapi | ✅ 稳定 | 支持多版本、过滤、格式选择 |

版本支持：

• OpenAPI 3.0.x ✅
• OpenAPI 3.1.x ✅
• Swagger 2.0 ✅

📝 开发

# 安装依赖
npm install

# 开发模式（自动重新编译）
npm run watch

# 构建
npm run build

# 清理构建产物
npm run clean

🐛 故障排除

问题：Claude Desktop 看不到工具

解决方案：

1. 检查配置文件路径和格式是否正确
2. 确保使用绝对路径
3. 完全退出并重启 Claude Desktop（不是最小化）

问题：导入失败

可能原因：

1. Token 或项目 ID 不正确
2. OpenAPI 规范格式不完整
3. 网络连接问题

解决方案：

• 检查 Token 和项目 ID 是否正确
• 验证 OpenAPI 规范是否包含必需字段（openapi/swagger, info, paths）
• 查看错误信息了解具体原因

问题：导入后没有创建任何内容

可能原因：

• 项目中已存在相同的 API（被设置为忽略）

解决方案：

• 修改 API 的路径或名称
• 使用 endpointOverwriteBehavior: "OVERWRITE_EXISTING" 选项覆盖现有接口
• 在 Apifox Web 界面检查导入结果

问题：导出失败或返回空数据

可能原因：

• 项目中没有接口
• Token 权限不足

解决方案：

• 检查项目中是否有接口
• 确认 Token 有读取权限

📚 相关文档

• Apifox Open API 文档
  • 导入 OpenAPI 文档
  • 导出 OpenAPI 文档
• Model Context Protocol

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

如果你发现了更多可用的 Apifox Open API 端点，欢迎分享。

Made with ❤️ for the Apifox community