Postman MCP

Sync your API code into Postman collections — body, params, auth, responses, tests, and examples — with zero manual fill, straight from Claude Code.

OpenAPI-first · code-parsing fallback · a diff before every write.

Documentation · Quickstart · Commands · Roadmap

Demo — an animated syncapi → diff → write recording goes here at launch (see assets/README.md).

/postman:syncapi createPayment --into payments

SYNC PREVIEW — POST /payments  →  collection / payments   [NEW] [openapi]

+ Request    POST {{base_url}}/payments
+ Auth       Bearer {{token}}              (from require_auth middleware)
+ Body       { "amount": 4200, "currency": "USD", "method": "card" }
+ Responses  201 Created, 400, 401, 422, 500
+ Tests      status(201) · schema(PaymentResponse) · business(amount > 0)
+ Examples   1 success, 4 error

Write? [y / n]

The problem

API code and Postman drift apart the moment you ship. Every new route, changed body shape, or added error response means going back into Postman by hand — re-typing fields, re-writing example data, re-doing test scripts. The work is mechanical, constant, and easy to skip, so collections rot. A rotten collection is worse than none: teammates trust it, then get burned by a stale endpoint.

The code already contains everything Postman needs — routes, types, middleware, comments. There's no reason a human should be the copy machine between them.

Related MCP server: Postman MCP Generator

Why Postman MCP

• Zero manual fill. Body, params, auth headers, every response, examples, and test scaffolds — all generated from your code.

• OpenAPI-first. When your framework emits a spec, one mapper covers FastAPI, NestJS, and Django REST Framework. No spec? It falls back to parsing your code.

• Diff before every write. Nothing reaches Postman until you've seen exactly what changes. There is no skip flag.

• Never destroys your work. Test scripts, manual examples, and edited descriptions are read back and preserved on every sync.

• Secrets never touch the repo. Your Postman API key is stored by reference — OS keychain, env var, or a gitignored file.

• Low token cost. syncchanges parses only what you changed and reads just the collection's basic structure — never a full re-scan.

Features

Architecture

Claude Code  ──slash commands──▶  Postman MCP Server (local)
             ◀──diffs/prompts───
                                      │
   ┌──────────┬──────────┬───────────┼──────────┬───────────┐
   ▼          ▼          ▼           ▼          ▼           ▼
Command    Input      Engine     Postman      Git        Config +
router     resolver  (builder)   client      reader      Secret store
         (OpenAPI/                (REST)    (diff since
          code)                              commit)

The five sync commands are one engine plus five selectors — the engine turns a normalized route model into a complete Postman request; the selectors decide which code goes in and where it lands. Full write-up in the architecture docs.

Installation

pip install postman-mcp

Requires Python ≥ 3.10, Claude Code, and a Postman personal API key. See Installation.

Quick start

# 1. install
pip install postman-mcp

# 2. set up this project (once)
cd my-api-project
postman-mcp init
#   → paste your Postman API key
#   → pick workspace + collection
#   → done: server registered, commands installed

# 3. open Claude Code in this project, then:
/postman:syncall        # first full sync
/postman:syncchanges    # from now on, after each change

# anytime something looks off:
postman-mcp doctor      # checks the whole setup chain

How it works

Three actions — install, init, then use inside Claude Code. After init, you never touch the terminal again for normal work.

Commands

Terminal-only: postman-mcp init, postman-mcp doctor, postman-mcp serve, postman-mcp version.

Examples

Runnable examples per framework live in examples/:

Configuration

All config lives in a small, committable, secret-free postman-mcp.json at your project root. See Configuration.

Framework support

OpenAPI-first for FastAPI, NestJS (@nestjs/swagger), and DRF (drf-spectacular); code-parsing fallback for all four, with Express as the primary code-path case. Details and known limits in the framework guides.

Roadmap

0.1.0 MVP → 0.2.0 hardening → 0.3.0 CI + Newman → 1.0.0 stable. See ROADMAP.md.

Contributing

Contributions welcome! See CONTRIBUTING.md, the Code of Conduct, and the development docs.

git clone https://github.com/logesh-works/postman-mcp
cd postman-mcp
python -m venv .venv && pip install -e ".[dev]"
pytest --cov

Security

The API key is stored by reference only and every write is gated behind a diff. Report vulnerabilities privately — see SECURITY.md.

License

MIT © Logeshkumar (logeshkumar.in).