ApiPost MCP

基于 MCP 协议和 ApiPost 官方 OpenAPI 实现的 API 管理工具。

功能

• 连接测试 - 一键验证MCP服务器状态和配置
• 工作空间管理 - 查看、切换团队和项目工作空间
• 目录管理 - 创建API文档目录，支持层级结构
• API接口管理 - 创建、查看、修改、删除接口文档
• 增量更新 - 支持字段级别的精确更新和删除
• 层级搜索 - 强化的目录层级搜索和父子关系定位
• 递归浏览 - 递归搜索子目录，支持深度限制
• 多维筛选 - 多维度搜索和批量操作
• 结构化显示 - 树形结构和分组显示
• 路径导航 - 完整路径显示，快速定位
• 权限管理 - 多种安全模式，灵活的操作权限控制

安装

方式一：通过 npx 使用（推荐）

# 直接运行（无需安装）
npx @funfe-dev/apipost-mcp

# 或者全局安装
npm install -g @funfe-dev/apipost-mcp

方式二：从源码安装

环境要求

在开始安装之前，请确保您的系统已安装以下环境：

| 环境 | 版本要求 | 说明 | |------|---------|------| | Node.js | >= 18.0.0 | JavaScript 运行环境（MCP SDK 官方最低要求） | | npm | >= 8.0.0 | Node.js 包管理器（通常随 Node.js 一起安装） |

环境安装指南

Node.js 安装：

• 访问 Node.js 官网 下载 LTS 版本
• 或使用包管理器：

  # macOS (使用 Homebrew)
  sudo brew install node
    
  # Ubuntu/Debian
  sudo apt update && sudo apt install nodejs npm
    
  # CentOS/RHEL
  sudo yum install nodejs npm

验证安装：

node --version   # 应显示 v18.0.0 或更高版本
npm --version    # 应显示 8.0.0 或更高版本

开始安装

git clone https://github.com/jlcodes99/apipost-mcp.git
cd apipost-mcp
npm install && npm run build

配置

方式一：使用 npx（推荐）

{
  "mcpServers": {
    "apipost": {
      "command": "npx",
      "args": ["@funfe-dev/apipost-mcp"],
      "env": {
        "APIPOST_TOKEN": "your_access_token_here",
        "APIPOST_HOST": "https://open.apipost.net",
        "APIPOST_SECURITY_MODE": "limited",
        "APIPOST_DEFAULT_TEAM_NAME": "你的团队名称",
        "APIPOST_DEFAULT_PROJECT_NAME": "你的项目名称"
      }
    }
  }
}

方式二：使用本地安装

{
  "mcpServers": {
    "apipost": {
      "command": "node",
      "args": ["/absolute/path/to/apipost-mcp/dist/index.js"],
      "env": {
        "APIPOST_TOKEN": "your_access_token_here",
        "APIPOST_HOST": "https://open.apipost.net",
        "APIPOST_SECURITY_MODE": "limited",
        "APIPOST_DEFAULT_TEAM_NAME": "你的团队名称",
        "APIPOST_DEFAULT_PROJECT_NAME": "你的项目名称"
      }
    }
  }
}

配置方式

方式一：项目配置文件（推荐）

在项目根目录创建 apipost.config.json 文件：

{
  "token": "your-apipost-token",
  "host": "https://open.apipost.net",
  "securityMode": "limited",
  "defaultTeamName": "我的团队",
  "defaultProjectName": "我的项目"
}

特性：

• 🤖 通过AI消息获取配置（向AI发送标准化请求）
• 📨 固定格式的提示词，便于AI识别和处理
• 📋 每次工具调用时自动刷新
• 🛡️ 敏感信息自动隐藏
• 📁 支持多种配置文件格式
• 🔄 智能后备机制（AI失败时使用直接shell命令）

方式二：环境变量

| 变量名 | 是否必需 | 说明 | |--------|------|------| | APIPOST_TOKEN | 否* | API访问令牌 | | APIPOST_HOST | 否 | API服务器地址，默认 https://open.apipost.net | | APIPOST_SECURITY_MODE | 否 | 安全模式：readonly, limited, full | | APIPOST_DEFAULT_TEAM_NAME | 否 | 默认团队名称 | | APIPOST_DEFAULT_PROJECT_NAME | 否 | 默认项目名称 |

配置优先级： 项目配置文件 > 环境变量 > 默认值

注意： * Token不是强制必需的，但没有Token时只能使用配置查看工具。

安全模式说明

| 模式 | 权限 | 说明 | |------|------|------| | readonly | 只读 | 仅允许查看接口列表和详情，禁止创建、修改、删除 | | limited | 读写 | 允许查看、创建、修改接口，禁止删除操作 | | full | 完全访问 | 允许所有操作，包括查看、创建、修改、删除 |

可用工具

| 工具 | 功能 | 主要参数 | |------|------|---------| | apipost_request_config_from_ai | 向AI请求配置获取 | request_type | | apipost_process_ai_config | 处理AI返回的配置 | config_file_path, config_content, not_found | | apipost_get_project_config | 获取项目配置 | show_content, refresh | | apipost_test_connection | 连接测试 | random_string | | apipost_workspace | 工作空间管理 | action (必需) | | apipost_create_folder | 创建目录 | name, parent_id | | apipost_smart_create | 创建接口 | method, url, name | | apipost_list | 强化列表搜索 | search, parent_id, target_type, show_structure, recursive, group_by_folder | | apipost_detail | 查看详情 | target_id | | apipost_update | 修改接口 | target_id, 其他可选 | | apipost_delete | 删除接口 | api_ids |

apipost_request_config_from_ai 说明

AI配置请求工具，向AI发送标准化的配置获取请求：

• 📨 生成固定格式的提示词，向AI发送配置获取请求
• 🤖 AI收到请求后会执行shell命令获取配置文件
• 📋 返回标准化的shell命令供AI执行
• 🔍 支持多种配置文件格式的自动搜索

使用示例：

apipost_request_config_from_ai request_type: "get_config"

工作流程：

1. MCP工具向AI发送标准化请求
2. AI收到请求并执行shell命令
3. AI返回配置文件路径和内容
4. 使用 apipost_process_ai_config 处理AI返回的信息

apipost_process_ai_config 说明

AI配置处理工具，处理AI返回的配置信息并更新MCP配置：

• 🤖 解析AI返回的配置文件内容
• ⚙️ 自动更新全局配置变量
• 🔄 刷新API客户端配置
• ✅ 验证配置有效性

使用示例：

# 如果AI找到了配置文件
apipost_process_ai_config config_file_path: "apipost.config.json" config_content: "{\"token\":\"your-token\",...}"

# 如果AI未找到配置文件
apipost_process_ai_config not_found: true

apipost_get_project_config 说明

项目配置获取工具，通过AI消息自动获取项目配置文件：

• 🤖 向AI发送标准化配置获取请求
• 📨 使用固定格式的提示词，便于AI识别处理
• 🔍 自动搜索多种配置文件（apipost.config.json, .apipostrc.json 等）
• 📋 显示配置文件路径和字段信息
• 🎯 展示当前使用的配置详情
• 🛡️ 自动隐藏敏感信息（如Token）
• 📝 提供配置文件模板和建议
• 🔄 智能后备机制（AI失败时使用直接方式）

使用示例：

apipost_get_project_config show_content: true

配置文件搜索顺序：

1. apipost.config.json
2. .apipostrc.json
3. config/apipost.config.json
4. .apipostrc

apipost_test_connection 说明

快速诊断工具，适合首次使用或故障排查：

• ✅ 验证MCP服务器连接状态
• 🔧 检查环境变量配置
• 🏢 显示当前工作空间信息
• 🛠️ 检查操作权限和安全模式
• 📊 提供系统环境详情
• 📋 显示配置来源信息

使用示例：

apipost_test_connection random_string: "test"

AI配置获取机制： 通过专门的工具与AI协作获取项目配置：

1. 请求配置：

   apipost_request_config_from_ai request_type: "get_config"

   工具会向AI发送标准化请求：

   🔍 MCP配置获取请求
      
   我是ApiPost MCP工具，需要你帮助我获取项目中的配置文件。
      
   请执行以下shell命令来获取项目中的apipost配置文件：
      
   ```bash
   # 检查并读取配置文件（按优先级顺序）
   for file in "apipost.config.json" ".apipostrc.json" "config/apipost.config.json" ".apipostrc"; do
     if [ -f "$file" ]; then
       echo "CONFIG_FILE_FOUND: $file"
       echo "CONFIG_CONTENT_START"
       cat "$file"
       echo "CONFIG_CONTENT_END"
       break
     fi
   done

2. 处理AI响应： AI执行命令后，使用以下工具处理结果：

   # 如果找到配置文件
   apipost_process_ai_config config_file_path: "apipost.config.json" config_content: "{配置内容}"
      
   # 如果未找到配置文件
   apipost_process_ai_config not_found: true

3. 自动配置提示：

   • 🤖 其他工具调用时会自动检查配置状态
   • 📋 如果缺少配置会提示使用AI配置获取流程
   • ✅ 配置完成后可正常使用所有API工具

零配置启动：

• ✅ 无需强制配置即可启动MCP服务器
• 🔍 apipost_get_project_config 工具始终可用
• ⚠️ 其他API工具需要配置Token后才能使用
• 💡 提供清晰的配置指导和错误提示

apipost_workspace 说明

统一的工作空间管理工具，支持以下操作：

| Action | 功能 | 主要参数 | 说明 | |--------|------|---------|------| | current | 查看当前工作空间 | show_all | 显示当前团队、项目信息，可选显示所有可用选项 | | list_teams | 列出团队 | show_details | 显示所有可用团队，标识当前团队 | | list_projects | 列出项目 | team_id, show_details | 显示指定团队的项目列表 | | switch | 切换工作空间 | team_id, project_id 或 team_name, project_name | 切换到指定的团队和项目 |

使用示例：

# 查看当前工作空间
apipost_workspace action: "current"

# 列出所有团队
apipost_workspace action: "list_teams" show_details: true

# 列出项目
apipost_workspace action: "list_projects" team_id: "your_team_id"

# 切换工作空间（支持按名称或ID）
apipost_workspace action: "switch" team_name: "团队名" project_name: "项目名"

apipost_create_folder 说明

API文档目录创建工具，支持在指定父目录下创建新的文件夹：

| 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | name | string | 是 | 目录名称 | | parent_id | string | 否 | 父目录ID，使用"0"表示根目录，默认为"0" | | description | string | 否 | 目录描述（可选） |

使用示例：

# 在根目录创建目录
apipost_create_folder name: "用户管理" description: "用户相关接口"

# 在指定目录下创建子目录
apipost_create_folder name: "认证接口" parent_id: "folder_123" description: "用户认证相关接口"

apipost_list 参数说明

| 参数 | 类型 | 说明 | |------|------|------| | search | string | 搜索关键词（接口名称、URL、方法、ID、描述） | | parent_id | string | 父目录ID，精确查找子项目。"0"为根目录 | | target_type | string | 类型筛选：api(仅接口)、folder(仅目录)、all(全部) | | show_structure | boolean | 显示树形结构，默认false为列表模式 | | show_path | boolean | 显示完整路径，默认false | | recursive | boolean | 递归搜索子目录，默认false | | depth | number | 深度限制（配合recursive），默认无限制 | | group_by_folder | boolean | 按目录分组显示，默认false | | limit | number | 显示数量限制（默认50，最大200） | | show_all | boolean | 显示全部（忽略limit限制） |

apipost_smart_create 说明

API接口文档生成器，支持通过分离参数创建完整的API文档，包括请求参数、响应格式、认证方式等：

| 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | method | string | 是 | HTTP方法：GET, POST, PUT, DELETE | | url | string | 是 | 接口URL路径 | | name | string | 是 | 接口名称 | | parent_id | string | 否 | 父目录ID，使用"0"表示根目录，默认为"0" | | description | string | 否 | 接口详细描述 | | headers | string | 否 | Headers参数JSON数组字符串 | | query | string | 否 | Query参数JSON数组字符串 | | body | string | 否 | Body参数JSON数组字符串 | | cookies | string | 否 | Cookies参数JSON数组字符串 | | auth | string | 否 | 认证配置JSON字符串 | | responses | string | 否 | 响应示例JSON数组字符串 |

使用示例：

# 在根目录创建接口
apipost_smart_create method: "POST" url: "/api/users" name: "创建用户"

# 在指定目录下创建接口
apipost_smart_create method: "GET" url: "/api/users/{id}" name: "获取用户详情" parent_id: "folder_123"

获取 Token

1. ApiPost OpenApi官方文档查看
2. 用户api_token。获取方式：Apipost客户端>工作台>项目设置>对外能力>open API

📝 更新日志

查看 CHANGELOG.md 了解版本更新信息。

💡 提示：这是一个专注于API接口管理的MCP工具，简化了接口创建和管理流程，提高团队协作效率。

版本特性

v1.9.0 主要特性

• ✅ 完整的MCP工具集：支持API文档的完整生命周期管理
• 🔧 智能工作空间管理：自动团队和项目切换
• 📋 强化列表搜索：支持递归搜索、分组显示、路径导航
• 🎯 精确更新机制：增量更新和字段级别控制
• 🛡️ 多级安全模式：readonly/limited/full权限控制
• 🏗️ 智能API模板生成：支持复杂参数和响应配置
• 🤖 AI配置获取：每次工具调用前自动向AI发送消息获取项目配置
• 🚀 零配置启动：无需强制配置即可启动，提供友好的配置指导
• 📱 用户友好界面：清晰的日志输出和错误提示

联系方式

• 📦 NPM包: @funfe-dev/apipost-mcp
• 🐛 问题反馈: GitHub Issues
• 🌟 项目主页: GitHub Repository

相关链接

• ApiPost OpenAPI 文档
• MCP 协议说明

⭐ 如果这个项目对你有帮助，请给我们一个星标！