postman-mcp-server by andy-zhangtao - MCP Server

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?

登录 Postman
前往 API Keys 设置
点击 "Generate API Key"
复制 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 考虑实现,参考 )

🗺️ 路线图

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

下一步计划:

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

🤝 贡献

欢迎 Issue 和 Pull Request!

贡献指南:

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

📄 许可证

MIT License - 详见文件

🙏 致谢

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

📞 联系方式

Issues: GitHub Issues
讨论: GitHub Discussions

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

andy-zhangtao/postman-mcp-server