Postman MCP Server

让 AI 助手(Claude)通过自然语言与 Postman 交互,轻松搜索和执行 API 请求

📋 简介

postman-mcp-server 是一个 Model Context Protocol (MCP) 服务器,它允许 AI 助手直接操作你的 Postman Collections,无需手动打开 Postman GUI。

核心功能

• ✅ 浏览 Workspaces & Collections: 列出所有 Postman 工作空间和集合
• ✅ 智能搜索: 用自然语言搜索 API 请求 (支持按名称、URL、方法搜索)
• ✅ 执行请求: 运行 API 请求并返回结果(支持环境变量)
• ✅ 查看配置: 获取请求的完整配置详情(JSON/YAML 格式)

典型使用场景

你: "我有哪些 Postman Collections?"
Claude: [列出所有 collections]

你: "帮我测试一下登录接口"
Claude:
  1. 搜索 "login" 相关请求
  2. 找到 "User Login" (POST /auth/login)
  3. 执行请求
  4. 返回结果: ✅ 200 OK, 响应时间 234ms

你: "用 staging 环境再测一次"
Claude: [使用 staging 环境变量重新执行]

你: "帮我查看这个接口的完整配置"
Claude: [返回 JSON/YAML 格式的请求配置]

---

🚀 快速开始

1. 前置要求

• Node.js >= 18.0.0
• Postman API Key (获取方式)
• Claude Desktop 或其他支持 MCP 的客户端

2. 安装

方式 A: 通过 npm 安装 (推荐)

npm install -g @ztao8607/postman-mcp-server

方式 B: 从源码安装

# 克隆仓库
git clone https://github.com/andy-zhangtao/postman-mcp-server.git
cd postman-mcp-server

# 安装依赖
npm install

# 编译
npm run build

3. 配置 API Key

# 方式 1: 使用 .env 文件
cp .env.example .env
# 编辑 .env,填入你的 API Key

# 方式 2: 直接设置环境变量
export POSTMAN_API_KEY=PMAK-your-api-key-here

4. 配置 Claude Desktop

编辑 Claude Desktop 配置文件:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

如果通过 npm 全局安装:

{
  "mcpServers": {
    "postman": {
      "command": "postman-mcp",
      "env": {
        "POSTMAN_API_KEY": "PMAK-your-api-key-here"
      }
    }
  }
}

如果从源码安装:

{
  "mcpServers": {
    "postman": {
      "command": "node",
      "args": ["/absolute/path/to/postman-mcp-server/dist/index.js"],
      "env": {
        "POSTMAN_API_KEY": "PMAK-your-api-key-here"
      }
    }
  }
}

注意: 请替换为你的实际 API Key!

5. 重启 Claude Desktop

重启后,在对话中可以看到 Postman 相关的工具。

---

🛠️ 可用工具

1. list_workspaces

列出所有 Postman Workspaces

参数:

• 无

示例:

你: "我有哪些 Postman Workspaces?"
你: "列出所有工作空间"

返回内容:

• Workspace ID
• 名称
• 类型 (personal, team, private, public, partner)
• 可见性
• 描述
• 更新时间

---

2. list_collections

列出所有 Postman Collections

参数:

• workspace_id (可选): 限定到特定 workspace

示例:

你: "列出我的所有 collections"
你: "显示某个 workspace 里的 collections"

---

3. search_requests

在 Collections 中搜索 API 请求

参数:

• query (必填): 搜索关键词
• collection_id (可选): 限定到特定 collection
• method (可选): 过滤 HTTP 方法 (GET, POST, etc.)
• limit (可选): 限制结果数量 (默认: 10)

示例:

你: "找一下所有支付相关的接口"
你: "搜索 POST 请求,关键词 user"

搜索语法:

• "login" - 搜索名称或 URL 包含 login 的请求
• "POST user" - 搜索 POST 方法且包含 user 的请求

---

4. run_request

执行 Postman 请求

参数:

• collection_id (必填): Collection ID
• request_id (必填): Request ID
• environment_id (可选): Environment ID
• variables (可选): 临时变量,覆盖环境变量

示例:

你: "执行这个登录接口,用 staging 环境"
你: "测试一下 User API 里的 Get User 接口"

返回内容:

• HTTP 状态码
• 响应时间
• 响应头和响应体
• 错误信息(如果失败)

---

5. get_request_details

获取指定 API 请求的完整配置详情

参数:

• collection_id (必填): Collection ID
• request_id (必填): Request ID (可以通过 search_requests 工具查找)
• format (可选): 输出格式,支持 json 或 yaml (默认: json)

示例:

你: "帮我查看登录接口的完整配置"
你: "把这个 API 的配置导出成 YAML 格式"
你: "这个接口都配置了哪些 headers?"

返回内容:

• 请求方法和 URL (包括 protocol、host、path、query 等完整信息)
• Headers 配置 (包括启用/禁用状态)
• Body 配置 (raw/urlencoded/formdata)
• Auth 配置 (bearer/basic/apikey)
• URL 变量说明
• 所属 Collection 信息

使用场景:

• 📋 查看请求的完整配置信息
• 🔍 调试请求参数和变量
• 📤 导出配置用于文档或其他工具
• 🔄 对比不同环境下的请求配置

---

📁 项目结构

postman-mcp-server/
├── src/
│   ├── index.ts              # MCP Server 入口
│   ├── postman/
│   │   ├── client.ts         # Postman API 客户端
│   │   └── types.ts          # 类型定义
│   ├── search/
│   │   └── searcher.ts       # 搜索引擎
│   ├── executor/
│   │   └── runner.ts         # Newman 执行器
│   └── tools/
│       ├── list-workspaces.ts
│       ├── list-collections.ts
│       ├── search-requests.ts
│       ├── run-request.ts
│       └── get-request-details.ts
├── examples/                  # 配置示例
├── ROADMAP.md                 # 开发路线图
└── README.md                  # 本文档

---

🔧 开发

# 安装依赖
npm install

# 开发模式 (自动编译)
npm run watch

# 手动测试 (需要先设置 POSTMAN_API_KEY)
npm run dev

# 代码检查
npm run lint

# 格式化代码
npm run format

---

🧪 测试

# 运行测试
npm test

# 监听模式
npm run test:watch

---

📖 常见问题

1. 如何获取 Postman API Key?

1. 登录 Postman
2. 前往 API Keys 设置
3. 点击 "Generate API Key"
4. 复制 Key (格式: PMAK-xxxxx)

2. API Key 安全吗?

• API Key 不会出现在 MCP 响应中
• API Key 不会被记录到日志
• 建议使用环境变量而不是硬编码

3. 为什么搜索不到我的请求?

检查以下几点:

• Collection 是否在你的 Postman 账号中
• API Key 是否有权限访问该 Collection
• 搜索关键词是否正确 (支持部分匹配)
• 尝试使用 list_collections 先确认 collection 存在

4. 执行请求失败怎么办?

常见原因:

• 环境变量未设置: 确保指定正确的 environment_id
• 网络错误: 检查目标 API 是否可访问
• 认证失败: 确认 request 中的 auth 配置是否正确

5. 支持哪些 Postman 功能?

当前支持 (v0.1):

• ✅ 执行 GET/POST/PUT/DELETE 等请求
• ✅ 环境变量替换
• ✅ 临时变量覆盖

暂不支持:

• ❌ Pre-request Scripts
• ❌ Test Scripts
• ❌ 批量执行
• ❌ Mock Servers

(这些功能在 Phase 2 考虑实现,参考 ROADMAP.md)

---

🗺️ 路线图

查看 ROADMAP.md 了解详细的开发计划。

下一步计划:

• 批量执行文件夹内所有请求
• 简单断言支持 (status code, response time)
• 执行历史记录
• 缓存优化

---

🤝 贡献

欢迎 Issue 和 Pull Request!

贡献指南:

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. Push 到分支 (git push origin feature/amazing-feature)
5. 提交 Pull Request

---

📄 许可证

MIT License - 详见 LICENSE 文件

---

🙏 致谢

• Postman - 强大的 API 平台
• Newman - Postman CLI 工具
• Model Context Protocol - AI 交互协议
• Anthropic - Claude AI

---

📞 联系方式

• Issues: GitHub Issues
• 讨论: GitHub Discussions

---

⭐ 如果这个项目对你有帮助,请给个 Star!