Postman MCP Server

Model Context Protocol (MCP) server for integrating Postman API with Cursor IDE, enabling automatic migration of API endpoints from .NET controllers to Postman collections.

🎯 Features

• ✅ List Collections: List all Postman collections in workspace

• ✅ Get Collection: Get detailed collection information

• ✅ Create Collection: Create new Postman collections

• ✅ Create Folder: Create folders to organize requests (with auto-fix validation errors)

• ✅ Create Request: Create API requests manually

• ✅ Update Request: Update existing requests

• ✅ Delete Request: Delete requests by ID or name (with recursive search)

• ✅ Sync from Controller: Automatically parse .NET controller code and migrate endpoints to Postman

📋 Requirements

• Node.js >= 18.0.0

• Postman API Key (Get from Postman Account Settings)

• Cursor IDE with MCP support

🚀 Quick Start

Step 1: Install Dependencies

Step 2: Build Project

Or use the setup script:

Step 3: Get Postman API Key

1. Go to Postman Account Settings

2. Create or copy your API Key (format: PMAK-xxxxx-xxxxx)

Step 4: Configure Cursor MCP Settings

Add to Cursor MCP configuration (usually in ~/.cursor/mcp.json or Cursor Settings):

macOS - Get absolute path:

Configuration:

Example for macOS:

Note: Replace /absolute/path/to/ with your actual absolute path.

Step 5: Restart Cursor IDE

1. Quit Cursor completely (Cmd + Q on macOS)

2. Reopen Cursor

3. Test: Type "List all Postman collections" in Cursor chat

📖 Usage Examples

1. List Collections

2. Create Collection

3. Create Folder

4. Create Request Manually

5. Auto-Sync from Controller (Recommended)

Use the custom command /migrate-endpoint-to-postman or manually:

The server will automatically:

• Parse all HTTP endpoints ([HttpGet], [HttpPost], etc.)

• Extract routes from [Route] attributes

• Extract API version from [ApiVersion] attributes

• Extract XML comments for descriptions

• Extract API Code and Screen ID from comments

• Generate request names: {API Code} - {API Name}

• Generate request bodies for POST/PUT/PATCH

• Handle path parameters ({id:guid} → :id)

• Handle query parameters ([FromQuery])

• Expand PagedRequest into pageNumber, pageSize, searchTerm

• Add Authorization header only if [Authorize] attribute is present

6. Delete Request

Or by ID:

🔧 API Reference

Tool: list_collections

• Description: List all Postman collections

• Parameters: None

• Returns: Array of collections with id, name, uid

Tool: get_collection

• Description: Get detailed collection information

• Parameters:

  • collectionId (string, required): Collection ID (UID)

• Returns: Full collection object with items, variables, etc.

Tool: create_collection

• Description: Create new Postman collection

• Parameters:

  • name (string, required): Collection name

  • description (string, optional): Collection description

• Returns: Created collection object

Tool: create_folder

• Description: Create folder in collection to organize requests

• Parameters:

  • collectionId (string, required): Collection ID

  • name (string, required): Folder name

  • description (string, optional): Folder description

• Returns: Updated collection object

• Features:

  • Auto-fixes invalid collection variables (type validation)

  • Creates folder with placeholder request (avoids empty folder validation error)

  • Preserves entire collection structure

Tool: create_request

• Description: Create API request in collection

• Parameters:

  • collectionId (string, required): Collection ID

  • name (string, required): Request name

  • method (string, required): HTTP method (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)

  • url (string, required): Full URL or path

  • headers (object, optional): HTTP headers as key-value pairs

  • body (object, optional): Request body for POST/PUT/PATCH

    • mode: "raw", "urlencoded", "formdata"

    • raw: JSON string for raw body

  • description (string, optional): Request description

  • folderId (string, optional): Folder ID to organize requests

• Returns: Updated collection object

Tool: update_request

• Description: Update existing request

• Parameters:

  • collectionId (string, required): Collection ID

  • requestId (string, required): Request ID (UID) to update

  • name, method, url, headers, body, description (optional): Fields to update

• Returns: Updated collection object

Tool: delete_request

• Description: Delete API request from collection

• Parameters:

  • collectionId (string, required): Collection ID

  • requestId (string, optional): Request ID (UID) to delete

  • requestName (string, optional): Request name to find and delete

• Returns: Updated collection object

• Features:

  • Delete by ID or name

  • Recursive search in folders

  • Auto-fixes collection variables

  • Preserves collection structure

Tool: sync_from_controller

• Description: Automatically migrate endpoints from .NET controller code

• Parameters:

  • collectionId (string, required): Postman collection ID

  • controllerCode (string, required): Full C# controller code with XML comments

  • baseUrl (string, required): Base URL (e.g., http://localhost:5020)

  • apiVersion (string, optional): API version (default: "1.0")

  • folderName (string, optional): Folder name to organize requests (will be created if not exists)

• Returns: Summary of created requests with endpoint details

• Features:

  • Parses [Route], [HttpGet], [HttpPost], [HttpPut], [HttpDelete], [HttpPatch] attributes

  • Extracts XML comments (/// <summary>, API Code:, Screen ID:)

  • Generates request names: {API Code} - {API Name} (from summary)

  • Generates request bodies from DTO properties

  • Handles path parameters ({id:guid} → :id Postman format)

  • Handles query parameters ([FromQuery])

  • Expands PagedRequest into individual query parameters

  • Adds Authorization header only if [Authorize] attribute is present

  • Replaces [controller] placeholder with actual controller name

  • Extracts major version from API version (e.g., "1.0" → "v1")

  • Uses {{baseUrl}} Postman variable for URLs

🎨 Controller Code Requirements

For sync_from_controller to work optimally:

• ✅ Controller must have [ApiController] attribute

• ✅ Methods must have HTTP method attributes ([HttpGet], [HttpPost], etc.)

• ✅ XML comments with /// <summary> for descriptions

• ✅ API Code: XXXX in comments for request naming

• ✅ Screen ID: XXXX in comments (optional)

Example:

Generated Request:

• Name: QS0041 - Get vendor quotation history for specified vendors within a specific ES Version

• URL: {{baseUrl}}/api/v1/Vendors/quotation-history?versionId=...&vendorId=...

• Method: GET

• Headers: Only Authorization if [Authorize] is present

🔄 Development Workflow

Workflow 1: Manual Migration (Step-by-step)

1. Create Collection for each system (PM, DC, ES, QS, Master)

2. Develop API in .NET controller

3. Create Request in Postman via Cursor prompt

4. Test in Postman

Workflow 2: Auto-Sync (Bulk Migration) ⭐ Recommended

1. Develop API in .NET controller with complete XML comments

2. Use or sync manually

3. Verify in Postman

4. Update if needed

Workflow 3: GitHub Actions Integration (Future)

Create GitHub Action workflow to auto-sync when PR is merged:

🔐 Security Notes

• API Key: Do not commit POSTMAN_API_KEY to git (already in .gitignore)

• Local Only: Server runs locally, not exposed externally

• Environment Variables: Use .env file if needed (do not commit)

🐛 Troubleshooting

Server Not Starting

• Check Node.js version: node --version (requires >= 18)

• Check build: npm run build

• Check absolute path in MCP config (must be absolute path)

• After code changes: Quit Cursor completely and rebuild with npm run build

Postman API Errors

• Verify API Key: Check key format (PMAK-...)

• Check API limits: Postman has rate limits

• Verify Collection ID: Collection ID must be UID (not name)

• Check workspace permissions: Need Editor or Admin role

Endpoints Not Parsed

• Ensure controller code has complete attributes

• Check XML comments format (must use ///)

• Verify route patterns

• Check for [ApiController] attribute

Request Names Not Correct

• Ensure API Code: XXXX is present in XML comments

• Check summary format in <summary> tags

• Rebuild MCP server after code changes: npm run build

Headers Not Added

• Authorization header is only added when [Authorize] attribute is explicitly present

• No default headers (X-API-Version, Accept, Content-Type) are added automatically

• Headers are only added when explicitly defined in code (e.g., [FromHeader] parameters)

📁 Project Structure

🛠️ Development

Run in Development Mode

Type Check

Build

Important: After making code changes, you must:

1. Quit Cursor completely

2. Run npm run build

3. Reopen Cursor

Or use the helper script:

📚 References

• Postman API Documentation

• MCP SDK Documentation

• Cursor MCP Setup

🗺️ Roadmap

✅ Completed Features

• List collections

• Get collection details

• Create collection

• Create folder (with auto-fix validation errors)

• Create request

• Update request

• Delete request (by ID or name, recursive search)

• Sync from .NET controller (parse routes, methods, parameters)

• Extract XML comments (summary, API Code, Screen ID)

• Generate request names: {API Code} - {API Name}

• Handle path/query parameters

• Expand PagedRequest into individual parameters

• Authorization header based on [Authorize] attribute

• No default headers (only explicit headers from code)

🔄 Planned Enhancements

Phase 1: Enhanced Parsing

• Support for [FromForm] parameters (multipart/form-data)

• Support for [FromHeader] parameters (already parsed, need to add to headers)

• Better DTO property type detection

• Support for nested DTOs

• Extract validation rules from FluentValidation

Phase 2: Advanced Features

• Update existing requests (detect changes and update)

• Delete deprecated endpoints

• Support for multiple API versions in same collection

• Generate Postman tests from controller code

• Support for authentication (JWT, API Key, etc.)

Phase 3: Integration

• GitHub Actions integration (auto-sync on PR merge)

• Support for other frameworks (FastAPI, Express.js, etc.)

• Export collection to OpenAPI/Swagger

• Import from OpenAPI/Swagger

📝 Best Practices

1. Naming: Use API Code in XML comments for consistent naming

2. Organization: Create folders by system/version for easy management

3. Documentation: Add descriptions for requests for better understanding

4. Testing: Test requests after migration to ensure correctness

5. Authorization: Use [Authorize] attribute explicitly when authentication is required

6. Headers: Only add headers when explicitly defined in code

🤝 Contributing

When adding new features:

1. Update this README with new features

2. Test thoroughly

3. Update roadmap section

4. Rebuild and test in Cursor

Last Updated: 2026-01-23
Version: 1.0.0
Status: ✅ Production Ready