# Postman Collection Generator MCP Server
An MCP (Model Context Protocol) server that automatically generates Postman collections from API codebases. Supports multiple frameworks including FastAPI, Spring Boot, Flask, Express, and any codebase with OpenAPI/Swagger specifications.
## Features
- 🚀 **Multi-Framework Support**: FastAPI, Spring Boot, Flask, Express, NestJS
- 📋 **OpenAPI/Swagger First**: Automatically detects and uses OpenAPI specs when available
- 🔍 **Smart Code Analysis**: Falls back to AST/pattern matching when no spec is found
- 🔐 **Authentication Support**: Handles Bearer, Basic, and API Key authentication
- 📁 **Organized Output**: Groups endpoints by tags or path segments
- 🎯 **Accurate Detection**: Extracts request bodies, parameters, and response examples
## Installation
### For End Users (via uvx)
The easiest way to use this MCP server is with `uvx`:
```bash
# Install and run directly
uvx postman-collection-generator-mcp
# Or install globally
uv tool install postman-collection-generator-mcp
```
### For Development
```bash
# Clone the repository
git clone https://github.com/yourusername/postman-collection-generator-mcp.git
cd postman-collection-generator-mcp
# Install dependencies with Poetry
poetry install
# Run in development
poetry run postman-collection-generator-mcp
```
## Configuration
### Claude Desktop Configuration
Add this to your Claude Desktop configuration file:
**For uvx installation (recommended):**
```json
{
"mcpServers": {
"postman-generator": {
"command": "uvx",
"args": ["--no-cache", "postman-collection-generator-mcp"],
"env": {
"BITBUCKET_EMAIL": "your-username",
"BITBUCKET_API_TOKEN": "your-app-password",
"output_directory": "/path/to/output"
}
}
}
}
```
**For local development:**
```json
{
"mcpServers": {
"postman-generator": {
"command": "poetry",
"args": ["run", "postman-collection-generator-mcp"],
"cwd": "/path/to/postman-collection-generator-mcp",
"env": {
"BITBUCKET_EMAIL": "your-username",
"BITBUCKET_API_TOKEN": "your-app-password",
"output_directory": "/path/to/output"
}
}
}
}
```
### Environment Variables
- `BITBUCKET_EMAIL`: Your Bitbucket username (not email)
- `BITBUCKET_API_TOKEN`: Bitbucket app password with repository read access
- `GITHUB_TOKEN`: GitHub personal access token (for private repos)
- `output_directory`: Where to save generated Postman collections (default: current directory)
## Usage
Once configured, you can use the following commands in Claude:
```
Generate a Postman collection from https://github.com/username/repo.git
Create Postman collection for https://bitbucket.org/team/api-project.git
```
The server will:
1. Clone the repository
2. Detect the framework and analyze the codebase
3. Extract all API endpoints with their parameters and examples
4. Generate a Postman v2.1 collection file
5. Save it to your output directory
## Supported Frameworks
### With Full Support
- **FastAPI** (Python) - Full OpenAPI integration
- **Spring Boot** (Java) - Annotation-based detection
- **Express** (Node.js) - Route pattern matching
- **Flask** (Python) - Decorator-based detection
- **Django REST** (Python) - ViewSet and path detection
### Coming Soon
- NestJS (TypeScript)
- Ruby on Rails
- ASP.NET Core
## Publishing Updates to PyPI
### One-Time Setup
```bash
# Configure PyPI token (get from https://pypi.org/manage/account/token/)
poetry config pypi-token.pypi YOUR-PYPI-TOKEN
```
### Publishing Updates Workflow
1. **Update Version**
```bash
# Update version in pyproject.toml
poetry version patch # for bug fixes (0.1.0 -> 0.1.1)
poetry version minor # for new features (0.1.0 -> 0.2.0)
poetry version major # for breaking changes (0.1.0 -> 1.0.0)
```
2. **Build Package**
```bash
poetry build
```
3. **Publish to PyPI**
```bash
poetry publish
```
4. **Test Installation**
```bash
# Test the published package
uvx --reinstall postman-collection-generator-mcp
```
### Automated Version Workflow
```bash
# Complete update workflow
poetry version patch && poetry build && poetry publish
```
### Users Update with uvx
After publishing, users can update with:
```bash
uvx --reinstall postman-collection-generator-mcp
```
## Development
### Running Tests
```bash
poetry run pytest
```
### Code Quality
```bash
# Format code
poetry run black .
# Lint code
poetry run ruff check .
```
### Local Testing with MCP Inspector
#### Option 1: Test Published Version
```bash
# Set environment variables
export BITBUCKET_EMAIL="your-username"
export BITBUCKET_API_TOKEN="your-app-password"
export output_directory="/tmp/postman-test"
# Run published version in HTTP mode
uvx postman-collection-generator-mcp@latest --transport http --port 8000
# Connect MCP Inspector to: http://localhost:8000/mcp
```
#### Option 2: Test Development Version
```bash
# From project directory
cd /path/to/postman-collection-generator-mcp
# Set environment variables
export BITBUCKET_EMAIL="your-username"
export BITBUCKET_API_TOKEN="your-app-password"
export output_directory="/tmp/postman-test"
# Run development version in HTTP mode
poetry run postman-collection-generator-mcp --transport http --port 8000
# Connect MCP Inspector to: http://localhost:8000/mcp
```
#### Using the Test Scripts
**Interactive MCP Inspector Testing:**
```bash
# Basic usage
./test_mcp_inspector.sh
# Test specific version
./test_mcp_inspector.sh --version 0.1.3
# Test latest version
./test_mcp_inspector.sh --latest
```
**Automated HTTP API Testing:**
```bash
# Test with default repository
./scripts/test_http_api.sh
# Test with custom repository
./scripts/test_http_api.sh "https://github.com/user/repo.git"
```
#### Testing with MCP Inspector
1. Open [MCP Inspector](https://inspector.mcphub.com/) or run locally
2. Enter URL: `http://localhost:8000/mcp`
3. Click Connect
4. Test tools:
- `generate_collection` with: `{"repo_url": "https://bitbucket.org/tymerepos/tb-payshap-svc.git"}`
- `get_server_info` with: `{}`
## Architecture
The server follows clean architecture principles:
- **Models**: Pydantic models for API endpoints and Postman collections
- **Analyzers**: Framework-specific endpoint extraction logic
- **Generators**: Postman collection generation from API models
- **Clients**: Git repository access with authentication support
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
MIT License - see LICENSE file for details
## Acknowledgments
- Built with [FastMCP](https://github.com/jlowin/fastmcp) framework
- Inspired by API development workflows and the need for automation
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/postman-collection-generator-mcp",
"name": "postman-collection-generator-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": "mcp, postman, api, collection, generator",
"author": "Your Name",
"author_email": "you@example.com",
"download_url": "https://files.pythonhosted.org/packages/90/26/f40c805bdc73fb92a92e2d44f1b771d165f23588950aa0c9222f64140e0a/postman_collection_generator_mcp-0.2.9.tar.gz",
"platform": null,
"description": "# Postman Collection Generator MCP Server\n\nAn MCP (Model Context Protocol) server that automatically generates Postman collections from API codebases. Supports multiple frameworks including FastAPI, Spring Boot, Flask, Express, and any codebase with OpenAPI/Swagger specifications.\n\n## Features\n\n- \ud83d\ude80 **Multi-Framework Support**: FastAPI, Spring Boot, Flask, Express, NestJS\n- \ud83d\udccb **OpenAPI/Swagger First**: Automatically detects and uses OpenAPI specs when available\n- \ud83d\udd0d **Smart Code Analysis**: Falls back to AST/pattern matching when no spec is found\n- \ud83d\udd10 **Authentication Support**: Handles Bearer, Basic, and API Key authentication\n- \ud83d\udcc1 **Organized Output**: Groups endpoints by tags or path segments\n- \ud83c\udfaf **Accurate Detection**: Extracts request bodies, parameters, and response examples\n\n## Installation\n\n### For End Users (via uvx)\n\nThe easiest way to use this MCP server is with `uvx`:\n\n```bash\n# Install and run directly\nuvx postman-collection-generator-mcp\n\n# Or install globally\nuv tool install postman-collection-generator-mcp\n```\n\n### For Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/postman-collection-generator-mcp.git\ncd postman-collection-generator-mcp\n\n# Install dependencies with Poetry\npoetry install\n\n# Run in development\npoetry run postman-collection-generator-mcp\n```\n\n## Configuration\n\n### Claude Desktop Configuration\n\nAdd this to your Claude Desktop configuration file:\n\n**For uvx installation (recommended):**\n```json\n{\n \"mcpServers\": {\n \"postman-generator\": {\n \"command\": \"uvx\",\n \"args\": [\"--no-cache\", \"postman-collection-generator-mcp\"],\n \"env\": {\n \"BITBUCKET_EMAIL\": \"your-username\",\n \"BITBUCKET_API_TOKEN\": \"your-app-password\",\n \"output_directory\": \"/path/to/output\"\n }\n }\n }\n}\n```\n\n**For local development:**\n```json\n{\n \"mcpServers\": {\n \"postman-generator\": {\n \"command\": \"poetry\",\n \"args\": [\"run\", \"postman-collection-generator-mcp\"],\n \"cwd\": \"/path/to/postman-collection-generator-mcp\",\n \"env\": {\n \"BITBUCKET_EMAIL\": \"your-username\",\n \"BITBUCKET_API_TOKEN\": \"your-app-password\",\n \"output_directory\": \"/path/to/output\"\n }\n }\n }\n}\n```\n\n### Environment Variables\n\n- `BITBUCKET_EMAIL`: Your Bitbucket username (not email)\n- `BITBUCKET_API_TOKEN`: Bitbucket app password with repository read access\n- `GITHUB_TOKEN`: GitHub personal access token (for private repos)\n- `output_directory`: Where to save generated Postman collections (default: current directory)\n\n## Usage\n\nOnce configured, you can use the following commands in Claude:\n\n```\nGenerate a Postman collection from https://github.com/username/repo.git\n\nCreate Postman collection for https://bitbucket.org/team/api-project.git\n```\n\nThe server will:\n1. Clone the repository\n2. Detect the framework and analyze the codebase\n3. Extract all API endpoints with their parameters and examples\n4. Generate a Postman v2.1 collection file\n5. Save it to your output directory\n\n## Supported Frameworks\n\n### With Full Support\n- **FastAPI** (Python) - Full OpenAPI integration\n- **Spring Boot** (Java) - Annotation-based detection\n- **Express** (Node.js) - Route pattern matching\n- **Flask** (Python) - Decorator-based detection\n- **Django REST** (Python) - ViewSet and path detection\n\n### Coming Soon\n- NestJS (TypeScript)\n- Ruby on Rails\n- ASP.NET Core\n\n## Publishing Updates to PyPI\n\n### One-Time Setup\n```bash\n# Configure PyPI token (get from https://pypi.org/manage/account/token/)\npoetry config pypi-token.pypi YOUR-PYPI-TOKEN\n```\n\n### Publishing Updates Workflow\n\n1. **Update Version**\n ```bash\n # Update version in pyproject.toml\n poetry version patch # for bug fixes (0.1.0 -> 0.1.1)\n poetry version minor # for new features (0.1.0 -> 0.2.0)\n poetry version major # for breaking changes (0.1.0 -> 1.0.0)\n ```\n\n2. **Build Package**\n ```bash\n poetry build\n ```\n\n3. **Publish to PyPI**\n ```bash\n poetry publish\n ```\n\n4. **Test Installation**\n ```bash\n # Test the published package\n uvx --reinstall postman-collection-generator-mcp\n ```\n\n### Automated Version Workflow\n```bash\n# Complete update workflow\npoetry version patch && poetry build && poetry publish\n```\n\n### Users Update with uvx\nAfter publishing, users can update with:\n```bash\nuvx --reinstall postman-collection-generator-mcp\n```\n\n## Development\n\n### Running Tests\n```bash\npoetry run pytest\n```\n\n### Code Quality\n```bash\n# Format code\npoetry run black .\n\n# Lint code\npoetry run ruff check .\n```\n\n### Local Testing with MCP Inspector\n\n#### Option 1: Test Published Version\n```bash\n# Set environment variables\nexport BITBUCKET_EMAIL=\"your-username\"\nexport BITBUCKET_API_TOKEN=\"your-app-password\"\nexport output_directory=\"/tmp/postman-test\"\n\n# Run published version in HTTP mode\nuvx postman-collection-generator-mcp@latest --transport http --port 8000\n\n# Connect MCP Inspector to: http://localhost:8000/mcp\n```\n\n#### Option 2: Test Development Version\n```bash\n# From project directory\ncd /path/to/postman-collection-generator-mcp\n\n# Set environment variables\nexport BITBUCKET_EMAIL=\"your-username\"\nexport BITBUCKET_API_TOKEN=\"your-app-password\"\nexport output_directory=\"/tmp/postman-test\"\n\n# Run development version in HTTP mode\npoetry run postman-collection-generator-mcp --transport http --port 8000\n\n# Connect MCP Inspector to: http://localhost:8000/mcp\n```\n\n#### Using the Test Scripts\n\n**Interactive MCP Inspector Testing:**\n```bash\n# Basic usage\n./test_mcp_inspector.sh\n\n# Test specific version\n./test_mcp_inspector.sh --version 0.1.3\n\n# Test latest version\n./test_mcp_inspector.sh --latest\n```\n\n**Automated HTTP API Testing:**\n```bash\n# Test with default repository\n./scripts/test_http_api.sh\n\n# Test with custom repository\n./scripts/test_http_api.sh \"https://github.com/user/repo.git\"\n```\n\n#### Testing with MCP Inspector\n1. Open [MCP Inspector](https://inspector.mcphub.com/) or run locally\n2. Enter URL: `http://localhost:8000/mcp`\n3. Click Connect\n4. Test tools:\n - `generate_collection` with: `{\"repo_url\": \"https://bitbucket.org/tymerepos/tb-payshap-svc.git\"}`\n - `get_server_info` with: `{}`\n\n## Architecture\n\nThe server follows clean architecture principles:\n\n- **Models**: Pydantic models for API endpoints and Postman collections\n- **Analyzers**: Framework-specific endpoint extraction logic\n- **Generators**: Postman collection generation from API models\n- **Clients**: Git repository access with authentication support\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Acknowledgments\n\n- Built with [FastMCP](https://github.com/jlowin/fastmcp) framework\n- Inspired by API development workflows and the need for automation",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for generating Postman collections from API codebases",
"version": "0.2.9",
"project_urls": {
"Homepage": "https://github.com/yourusername/postman-collection-generator-mcp",
"Repository": "https://github.com/yourusername/postman-collection-generator-mcp"
},
"split_keywords": [
"mcp",
" postman",
" api",
" collection",
" generator"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dd5edff84a86a7e32c9e4d2d611a77dbbe7dff5afe9188ef1f24b76080f42e4f",
"md5": "5f02e75a65f9f18227f5549739d32200",
"sha256": "2f932fed30d356a36087928ccd8450528b8dfc598e18ab82b105acd6965c6377"
},
"downloads": -1,
"filename": "postman_collection_generator_mcp-0.2.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5f02e75a65f9f18227f5549739d32200",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 31957,
"upload_time": "2025-07-24T06:28:57",
"upload_time_iso_8601": "2025-07-24T06:28:57.144754Z",
"url": "https://files.pythonhosted.org/packages/dd/5e/dff84a86a7e32c9e4d2d611a77dbbe7dff5afe9188ef1f24b76080f42e4f/postman_collection_generator_mcp-0.2.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9026f40c805bdc73fb92a92e2d44f1b771d165f23588950aa0c9222f64140e0a",
"md5": "d772e6098ec85faf395a46c154cb1aff",
"sha256": "d82d3ed8b294f4eee3871f76749eb1765fc004ceb6e55874af873ea88e710687"
},
"downloads": -1,
"filename": "postman_collection_generator_mcp-0.2.9.tar.gz",
"has_sig": false,
"md5_digest": "d772e6098ec85faf395a46c154cb1aff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 25697,
"upload_time": "2025-07-24T06:28:59",
"upload_time_iso_8601": "2025-07-24T06:28:59.012076Z",
"url": "https://files.pythonhosted.org/packages/90/26/f40c805bdc73fb92a92e2d44f1b771d165f23588950aa0c9222f64140e0a/postman_collection_generator_mcp-0.2.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 06:28:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "postman-collection-generator-mcp",
"github_not_found": true,
"lcname": "postman-collection-generator-mcp"
}
JSON
