Simple Newman MCP

简单纽曼MCP服务器

一个模型上下文协议（MCP）服务器，用于通过Newman运行Postman集合，并完全集成API。

特性

• ✅ 基于stdio的MCP服务器 使用JSON-RPC协议
• ✅ 4个核心MCP工具:

- get_workspaces -列出所有可访问的Postman工作区 - get_collections -列出Postman API或本地文件中的集合 - get_collection -检索特定收藏详细信息 - run_collection -使用JUnitXML报告执行Newman测试

• ✅ 全面的错误处理 带有详细的错误信息
• ✅ Docker支持 体积安装到 /etc/newman
• ✅ 本地和云集合 -适用于Postman API和本地JSON文件
• ✅ VS代码/AI助手集成 通过MCP协议

快速开始

使用Docker

1. 构建Docker镜像：

   docker build -t newman-mcp-server -f Dockerfile.mcp .

1. 配置您的MCP客户端：

复制 mcp.json 到IDE配置目录并设置 POSTMAN_API_KEY

1. 服务器由您的MCP客户端（VS代码等）自动调用

Docker容器在需要时通过stdio传输运行。

直接使用Node.js

1. 安装依赖项：

   npm install

1. 配置环境：

   cp .env.example .env
   # Edit .env and add your POSTMAN_API_KEY

1. 配置您的MCP客户端：

使用 newman-local 配置从 mcp.json 在IDE中

1. 服务器通过MCP客户端按需运行

MCP协议

此服务器实现 模型上下文协议（MCP） 通过JSON-RPC消息传递使用stdio传输。

运作原理

1. 标准运输：服务器通过stdin/stdout进行通信
2. JSON-RPC：所有消息均遵循JSON-RPC 2.0格式
3. 按需执行：您的MCP客户端（VS Code等）在需要时启动服务器
4. 工具调用：AI助手可以调用工具来运行Postman收藏

JSON-RPC消息示例

初始化：

{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}

列出工具：

{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}

呼叫工具：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "run_collection",
    "arguments": {
      "collection": "my-collection.json"
    }
  }
}

MCP工具

1.get_workspaces

列出可使用API密钥访问的所有Postman工作区。

论据： 无

通过AI助手使用：

"List my Postman workspaces"

2.集合

列出Postman API和/或本地文件中的集合。

论据：

• workspaceId （可选）：按工作区筛选
• includeLocal （可选，默认值：true）：包括本地集合文件

通过AI助手使用：

"Show me all my Postman collections"
"List collections in workspace ABC123"

3.收集

检索特定集合的详细信息。

论据：

• collectionId （必填）：集合UID

通过AI助手使用：

"Get details for collection 12345-67890-abcdef"
"Show me the API Tests collection"

4.运行收集

使用Newman执行集合并生成测试报告。

论据：

• collection （必需）：集合UID或本地文件名
• environment （可选）：环境UID或本地文件名
• reporters （可选，默认值：\[“cli”，“junit”\]）：报告器类型
• iterationCount （可选，默认值：1）：迭代次数
• bail （可选，默认值：false）：第一次失败时停止
• outputFile （可选）：自定义JUnitXML输出路径

通过AI助手使用：

"Run my-api-tests.json collection"
"Execute the API integration tests with staging environment"
"Run tests and stop on first failure"

Docker配置

数据载体安装

当前项目工作区已装载到 /etc/newman 在容器中。这允许：

• 读取本地收藏文件
• 将JUnitXML测试报告写入项目目录
• 访问环境文件

塑造形象

# Build the Docker image
docker build -t newman-mcp-server -f Dockerfile.mcp .

通过MCP客户端配置自动调用映像

直接使用Newman CLI

# Start the CLI container
docker-compose --profile cli run --rm newman-cli

# Inside the container, run Newman commands
newman run /etc/newman/my-collection.json -r junit --reporter-junit-export /etc/newman/report.xml

环境变量

测试

使用MCP协议测试客户端测试服务器：

node src/mcpTestClient.js

或者在配置后通过您的AI助手测试单个工具。

VS代码集成

复制 mcp.json 或使用以下配置：

{
  "mcpServers": {
       "newman-docker": {
         "command": "docker",
         "args": [
           "run", "-i", "--rm",
           "-v", "${workspaceFolder}:/etc/newman",
           "-e", "POSTMAN_API_KEY",
           "newman-mcp-server"
         ],
         "env": {
           "POSTMAN_API_KEY": "your_key_here"
         }
       }
  }
}

将其放入IDE的MCP配置文件中。

故障排除

未设置POSTMAN_API_KEY

症状： 工具返回“未配置POSTMAN_API_KEY”

解决方案：

1. 从获取API密钥https://postman.co/settings/me/api-keys
2. 将其添加到 env 你的部分 mcp.json 配置
3. 重新启动MCP客户端（VS代码等）

未找到集合

症状： “无法获取集合”错误

解决方案：

• 对于Postman API：验证集合UID是否正确
• 对于本地文件：确保文件位于工作区目录中
• 检查文件权限

报告未保存

症状： JUnit XML报告未出现在工作区中

解决方案：

• 验证docker-compose.yml中的卷装载
• 检查WORKSPACE_DIR环境变量
• 确保目录的写入权限

建筑

newman-mcp/
├── src/
│   ├── server.js           # Main MCP server
│   ├── PostmanUtils.js     # Postman API & Newman integration
│   └── mcpTestClient.js    # Test client
├── docker-compose.yml      # Docker orchestration
├── Dockerfile.mcp          # MCP server container
├── package.json            # Node dependencies
└── .env                    # Environment configuration

安全考虑

1. API密钥保护：从不在中提交API密钥 mcp.json -使用环境变量
2. stdio运输：服务器仅通过stdin/stdout通信，没有网络暴露
3. Docker隔离：在Docker中运行提供了额外的安全层
4. 验证：所有输入在执行前都经过验证
5. 错误处理：敏感信息不会在错误消息中泄露

许可证

麻省理工学院

贡献

欢迎投稿！请打开问题或提交拉取请求。

支持

有关问题和疑问，请在GitHub上打开问题。