Errorrrrr/apifox-mcp-server

Apifox MCP 服务器

这是一个 MCP（Model Context Protocol）服务器，实现了一个可以将 OpenAPI、Swgger 格式的 JSON 数据导入到 Apifox 项目中的工具。

功能特性

• 📡 Apifox 导入工具: 将 OpenAPI 3、Swagger 2 格式的 JSON 数据导入到 Apifox 项目中

安装依赖

pip install -r requirements.txt

MCP 服务器配置

1. 启动服务器

有两种方式启动服务器：

方式一：直接启动

python main.py

方式二：使用启动脚本

./start_server.sh

2. MCP 客户端配置

Claude Desktop 配置

在 Claude Desktop 的配置文件中添加服务器配置：

macOS 配置文件位置： ~/Library/Application Support/Claude/claude_desktop_config.json

Windows 配置文件位置： %APPDATA%\Claude\claude_desktop_config.json

配置示例：

{
  "mcpServers": {
    "apifox-mcp-server": {
      "command": "python",
      "args": ["/path/to/your/apifox-mcp-server/main.py"],
      "env": {
        "APIFOX_TOKEN": "your-apifox-token",
        "APIFOX_PROJECT_ID": "your-project-id"
      }
    }
  }
}

💡 提示： 完整的配置示例和说明请参考项目中的 mcp_config_example.json 和 MCP_CONFIG_README.md 文件

其他 MCP 客户端配置

对于其他支持 MCP 的客户端，请参考相应客户端的文档配置 stdio 连接：

python /path/to/apifox-mcp-server/main.py

3. 验证配置

配置完成后，重启 MCP 客户端，您应该能够看到 import_api 工具可用。

4. 环境变量配置

在 MCP 配置文件的 env 字段中设置以下环境变量：

5. 项目路径配置

请确保在配置文件中使用绝对路径，例如：

• 正确： /Users/username/projects/apifox-mcp-server/main.py
• 错误： ./main.py 或 main.py

使用方法

工具说明

import_api

调用工具，将 OpenAPI 3、Swagger 2 格式的 JSON 数据导入到指定的 Apifox 项目中。

参数：

• project_id (可选): Apifox 项目 ID，优先使用环境变量 APIFOX_PROJECT_ID
• input (必需): 要导入的 OpenAPI 3 或 Swagger 2 格式的 JSON 字符串数据（需要转义）
• headers (可选): HTTP 请求头，Authorization 自动从环境变量 APIFOX_TOKEN 添加
• timeout (可选): 请求超时时间，默认 30 秒

配置环境变量后的简化使用：

{
  "input": "{\"swagger\": \"2.0\", \"info\": {\"title\": \"API文档\", \"version\": \"1.0.0\"}, \"paths\": {...}}"
}

完整参数使用（覆盖环境变量）：

{
  "project_id": "specific-project-id",
  "input": "{\"swagger\": \"2.0\", \"info\": {\"title\": \"API文档\", \"version\": \"1.0.0\"}, \"paths\": {...}}",
  "headers": {
    "Authorization": "Bearer specific-token"
  },
  "timeout": 60
}

重要说明：

• 优先使用环境变量配置，简化工具调用
• Authorization 格式为 Bearer {token}，从环境变量 APIFOX_TOKEN 自动添加
• X-Apifox-Api-Version: 2024-03-28 会自动添加，无需手动指定
• 支持 OpenAPI 3.0+ 和 Swagger 2.0 格式

API Token 配置

获取 Apifox API Token

1. 登录 Apifox
2. 点击右上角头像，进入「账号设置」
3. 在左侧菜单中选择「API 访问令牌」
4. 点击「生成新令牌」按钮
5. 输入令牌名称（如：MCP Server）
6. 选择合适的过期时间
7. 点击「生成」并复制生成的 token
8. 在请求头中使用：Authorization: Bearer {你的token}

获取项目 ID

1. 打开 Apifox 并进入目标项目
2. 在项目设置页面可以找到项目 ID
3. 或者在项目 URL 中获取项目 ID

故障排除

常见问题

1. 工具不可用

   • 检查 MCP 服务器是否正常启动
   • 确认配置文件中的路径是否正确
   • 重启 MCP 客户端

2. 认证失败 (401)

   • 检查 API Token 是否正确
   • 确认 Token 是否已过期
   • 验证 Token 格式：Bearer {token}

3. 项目不存在 (404)

   • 检查项目 ID 是否正确
   • 确认 Token 是否有该项目的访问权限

4. JSON 格式错误 (422)

   • 验证输入的 JSON 格式是否正确
   • 确认是否为有效的 OpenAPI/Swagger 格式

5. 项目 ID 未提供

   • 检查环境变量 APIFOX_PROJECT_ID 是否正确设置
   • 或在工具调用时提供 project_id 参数

6. 认证信息未提供

   • 检查环境变量 APIFOX_TOKEN 是否正确设置
   • 或在工具调用时的 headers 中提供 Authorization

调试模式

启动服务器时会显示详细日志，包括：

• API 调用信息
• 请求数据长度
• 响应状态码
• 错误详情

项目结构

apifox-mcp-server/
├── main.py              # 主服务器代码
├── requirements.txt     # 依赖管理
├── README.md           # 项目说明
├── start_server.sh         # 启动脚本
├── test_example.py         # 测试示例
├── config_example.json     # Swagger 2.0 格式示例
├── mcp_config_example.json # MCP 客户端配置示例
└── MCP_CONFIG_README.md    # MCP 配置详细说明