mirror of https://github.com/Postman-Devrel/postman-claude-code-plugin.git synced 2026-04-16 10:29:58 +00:00

Files

Sterling Chin 3f03fc19d3 feat: add 8 API lifecycle commands

Replace monolithic postman.md with focused, namespaced commands:
- setup: guided API key config and workspace verification
- sync: create/update collections from OpenAPI specs
- codegen: generate typed client code from collections
- search: discover APIs across private workspaces
- test: run collection tests and diagnose failures
- mock: create mock servers with auto-generated examples
- docs: analyze, improve, and publish API documentation
- security: OWASP API Top 10 security audit

Each command has proper frontmatter, error handling with actionable
next steps, and handles known MCP limitations (async polling, private
search, etc.).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-12 17:55:22 -08:00

2.9 KiB

Raw Blame History

description, allowed-tools

description	allowed-tools
Set up Postman MCP Server. Configure API key, verify connection, select workspace.	mcp__postman__*

First-Run Configuration

Walk the user through Postman setup for Claude Code. Validate everything works before they use other commands.

Workflow

Step 1: Check MCP Connection

Verify the Postman MCP Server is available by calling getAuthenticatedUser.

If it works: Skip to Step 3 (workspace verification).

If it fails or tools aren't available: Proceed to Step 2.

Step 2: Configure API Key

Let's set up Postman for Claude Code.

1. Go to: https://postman.postman.co/settings/me/api-keys
2. Click "Generate API Key"
3. Name it "Claude Code"
4. Copy the key (starts with PMAK-)

Then set it as an environment variable:

  export POSTMAN_API_KEY=PMAK-your-key-here

Add it to your shell profile (~/.zshrc or ~/.bashrc) to persist across sessions.

Wait for the user to confirm they've set the key. Then verify with getAuthenticatedUser.

If 401: "API key was rejected. Check for extra spaces or generate a new one at https://postman.postman.co/settings/me/api-keys"

If timeout: "Can't reach the Postman MCP Server. Check your network and https://status.postman.com"

Step 3: Workspace Verification

After successful connection:

Call getWorkspaces to list workspaces
Call getCollections with the first workspace ID to count collections
Call getAllSpecs with the workspace ID to count specs

Present:

Connected as: <user name>

Your workspaces:
  - My Workspace (personal) — 12 collections, 3 specs
  - Team APIs (team) — 8 collections, 5 specs

You're all set.

If workspace is empty:

Your workspace is empty. You can:
  /postman:sync     — Push a local OpenAPI spec to Postman
  /postman:search   — Search the public Postman API Network

Step 4: Suggest First Command

Based on what the user has:

Has collections:

Try one of these:
  /postman:search   — Find APIs across your workspace
  /postman:test     — Run collection tests
  /postman:codegen  — Generate client code from a collection

Has specs but no collections:

Try this:
  /postman:sync — Generate a collection from one of your specs

Empty workspace:

Try this:
  /postman:sync — Import an OpenAPI spec from your project

Error Handling

MCP tools not available: "The Postman MCP Server isn't loaded. Make sure the plugin is installed and restart Claude Code."
API key not set: Walk through Step 2 above.
401 Unauthorized: "Your API key was rejected. Generate a new one at https://postman.postman.co/settings/me/api-keys"
Network timeout: "Can't reach the Postman MCP Server. Check your network and https://status.postman.com for outages."
Plan limitations: "Some features (team workspaces, monitors) require a paid Postman plan. Core commands work on all plans."

2.9 KiB Raw Blame History