Postman Docker 镜像

Postman MCP Server 技术文档

1. 镜像概述和主要用途

Postman MCP Server（模型上下文协议服务器）用于将AI代理、助手和聊天机器人直接连接到Postman上的API。通过自然语言提示，AI可自动化操作Postman集合、环境、工作空间等资源，实现API开发、测试与管理的智能化流程。

关于MCP协议的更多信息：https://www.anthropic.com/news/model-context-protocol

2. 核心特性

2.1 基本信息

2.2 支持的工具

MCP Server提供38个工具，覆盖Postman资源的创建、查询、更新等核心操作，包括集合管理、环境配置、模拟服务器部署、API规范生成等。部分工具如下表：

3. 使用场景和适用范围

3.1 适用场景

• API开发自动化：通过自然语言指令创建集合、请求、响应，减少手动操作。
• 测试与模拟服务：快速生成模拟服务器，支持API测试环境搭建。
• 团队协作管理：批量创建工作空间、管理团队资源权限，适配企业级协作流程。
• AI驱动的API治理：结合LLM自动生成API规范（如OpenAPI）、同步集合与规范。

3.2 适用用户

• API开发者、测试工程师
• 依赖Postman进行API管理的团队
• 需要通过自然语言接口自动化Postman操作的AI应用开发者

4. 部署与配置

4.1 Docker快速启动

bash
docker run -d \
  --name postman-mcp-server \
  -p 8080:8080 \
  -e POSTMAN_API_KEY="your-postman-api-key" \
  -e LOG_LEVEL="info" \
  docker.xuanyuan.run/mcp/postman:latest

参数说明：

• -p 8080:8080：映射容器端口到主机（默认服务端口8080）。
• POSTMAN_API_KEY：Postman认证密钥（必填，从Postman账户设置中获取）。
• LOG_LEVEL：日志级别（可选，默认info，支持debug/warn/error）。

4.2 Docker Compose配置

yaml
version: '3.8'
services:
  mcp-server:
    image: docker.xuanyuan.run/mcp/postman:latest
    container_name: postman-mcp-server
    ports:
      - "8080:8080"
    environment:
      - POSTMAN_API_KEY=your-postman-api-key
      - LOG_LEVEL=info
      - WORKSPACE_ID=default-workspace-id  # 可选，默认工作空间ID
    restart: unless-stopped
    volumes:
      - ./config:/app/config  # 挂载配置文件目录（如需要自定义工具参数）

4.3 签名验证

为确保镜像完整性，可通过cosign验证签名：

bash
COSIGN_REPOSITORY=mcp/signatures cosign verify mcp/postman --key https://raw.githubusercontent.com/docker/keyring/refs/heads/main/public/mcp/latest.pub

5. 工具详情

5.1 集合管理工具

createCollection

描述：使用https://schema.postman.com/collection/json/v2.1.0/draft-07/docs/index.html创建集合。

参数：

注意事项：

• 若未指定workspace，集合将创建在用户拥有的最旧个人工作空间中。

getCollection

描述：查询指定集合的详细信息（符合Postman Collection Format规范）。

参数：

注意事项：

• 完整返回字段参考https://schema.postman.com/collection/json/v2.1.0/draft-07/docs/index.html。

5.2 环境管理工具

createEnvironment

描述：创建环境（存储API请求所需的变量配置）。

参数：

注意事项：

• 请求体大小不超过30MB。
• 若返回411 Length Required错误，需手动添加Content-Length请求头。

5.3 工作空间管理工具

createWorkspace

描述：创建新工作空间（支持个人/团队/私有/公开等可见性类型）。

参数：

注意事项：

• 用户需具备工作空间创建权限（团队管理员可配置权限）。
• 公开团队工作空间名称需全局唯一，且存在创建频率限制。

5.4 API规范工具

createSpec

描述：在Spec Hub中创建API规范（支持单文件/多文件，OpenAPI 3.0/AsyncAPI 2.0）。

参数：

注意事项：

• 文件路径含/时自动创建文件夹（如components/schemas.json生成components文件夹）。
• 多文件规范仅支持一个根文件，单个文件大小不超过10MB。

5. 验证与安全

5.1 镜像签名验证

使用cosign验证镜像完整性：

bash
COSIGN_REPOSITORY=mcp/signatures cosign verify mcp/postman --key https://raw.githubusercontent.com/docker/keyring/refs/heads/main/public/mcp/latest.pub

5.2 许可证

本镜像基于Apache License 2.0开源协议，详见https://github.com/postmanlabs/postman-mcp-server/blob/main/LICENSE。