Apifox MCP 服务器

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

这是一个 Model Context Protocol (MCP) 服务器允许 Claude DesktopClaude CodeCursor 等 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

步骤

获取 Token登录 Apifox 头像账号设置 API 访问令牌新建令牌
获取 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

步骤

打开 Cursor 设置Cursor Settings > Features > MCP
点击 + Add New MCP Server 按钮

填写配置信息

Name: apifox
Command: npx

Args:

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

Transport: stdio

保存配置

使用提示

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

4. 重启客户端

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

版本管理说明

为什么使用 @latest

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

查看当前版本

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

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

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

其他版本管理方式

指定具体版本适合生产环境

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

全局安装更快的启动速度
```
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" 只导出用户相关接口

示例 1Summary 模式推荐

{
  "mode": "summary"
}

返回结果

 接口文档概览Summary 模式

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

 目录结构和接口列表

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

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

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

示例 2Full 模式 + 路径过滤

{
  "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 看不到工具

解决方案

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

问题导入失败

可能原因

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

解决方案

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

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

可能原因

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

解决方案

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

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

可能原因

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

解决方案

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

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request

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

Made with for the Apifox community

服务配置

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

来源

来源：github
链接：https://github.com/Warren-W/apifox-mcp

apifox-mcp

Apifox MCP 服务器

主要功能

快速开始

1. 安装

方式 1: 使用 npx推荐

方式 2: 本地安装

2. 获取 API Token 和项目 ID

3. 配置 MCP 客户端

3.1 Claude Desktop

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

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

方式 3: 使用 npm link 后

3.2 Claude Code

3.3 Cursor

4. 重启客户端

版本管理说明

使用方法

在 MCP 客户端中使用

可用工具

1. import_openapi - API 导入推荐

2. export_openapi - API 导出

使用场景

场景 1首次创建 API 文档

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

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

API 响应格式

命令行使用

技术栈

关于 Apifox Open API

开发

故障排除

问题Claude Desktop 看不到工具

问题导入失败

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

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

相关文档

许可证

贡献

服务配置

来源

1. `import_openapi` - API 导入推荐

2. `export_openapi` - API 导出