| Name | shippo-mcp JSON |
| Version |
0.1.2
JSON |
| download |
| home_page | None |
| Summary | An unofficial MCP server for Shippo shipping API integration |
| upload_time | 2025-07-16 21:18:01 |
| maintainer | None |
| docs_url | None |
| author | Foad Kesheh |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Shippo MCP Server
A Model Context Protocol (MCP) server that integrates with the [Shippo shipping API](https://goshippo.com/) to provide shipping functionality through an AI assistant. This server enables you to validate addresses, get shipping rates, create shipments, generate shipping labels, track packages, manage carrier accounts, and handle refunds.
## Features
- **Address Validation**: Validate shipping addresses using Shippo's address validation service
- **Shipping Rates**: Get real-time shipping rates from multiple carriers
- **Shipment Management**: Create, list, and retrieve detailed shipment information
- **Label Creation**: Generate shipping labels for packages
- **Transaction Management**: List and manage shipping label transactions
- **Refund Processing**: Create and track refunds for shipping labels
- **Package Tracking**: Track packages using tracking numbers
- **Carrier Management**: List and manage configured carrier accounts
## Prerequisites
1. **Homebrew** (macOS/Linux): Install from [brew.sh](https://brew.sh/)
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
2. **uv** (Python package manager): Install via Homebrew
```bash
brew install uv
```
3. **Python 3.13+**: This project requires Python 3.13 or higher (uv will handle this)
4. **Shippo Account**: Sign up for a free [Shippo account](https://apps.goshippo.com/join)
5. **API Key**: Generate an [API Token](https://docs.goshippo.com/docs/guides_general/authentication/) from your Shippo dashboard
## Installation
1. Clone or download this repository
2. Install dependencies using uv:
```bash
uv install
```
## Configuration
The server gets the Shippo API key from environment variables. You can set it either:
1. **Via MCP client configuration** (recommended for production)
2. **Via command line** for testing:
```bash
export SHIPPO_API_KEY=shippo_test_your_api_key_here
```
> **Note**: Use a test API key (starts with `shippo_test_`) for development and testing. Only use live API keys for production.
## Usage
### Starting the Server
#### For stdio transport (MCP client integration)
```bash
export SHIPPO_API_KEY=shippo_test_your_api_key_here && uv run --with shippo-mcp shippo-mcp stdio
```
#### For HTTP transport (Inspector compatible)
```bash
export SHIPPO_API_KEY=shippo_test_your_api_key_here && uv run --with shippo-mcp shippo-mcp server
```
The server will be available at: http://127.0.0.1:8000/mcp
### Getting Help
```bash
uv run --with shippo-mcp shippo-mcp --help
```
### MCP Client Configuration
#### Claude Desktop Configuration
Add this configuration to your Claude Desktop config file (usually located at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"shippo": {
"command": "/opt/homebrew/bin/uv",
"args": [
"run",
"--with",
"shippo-mcp",
"shippo-mcp",
"stdio"
],
"env": {
"SHIPPO_API_KEY": "shippo_test_your_api_key_here"
}
}
}
}
```
### Available Tools
#### Address & Validation
##### 1. `validate_address`
Validate a shipping address to ensure it's deliverable.
**Parameters:**
- `name` (required): Recipient name
- `street1` (required): Primary street address
- `city` (required): City name
- `state` (required): State/province code
- `zip_code` (required): ZIP/postal code
- `country` (optional): Country code (default: "US")
- `street2` (optional): Secondary address line
- `company` (optional): Company name
- `phone` (optional): Phone number
- `email` (optional): Email address
#### Rates & Shipping
##### 2. `get_shipping_rates`
Get shipping rates for a package between two addresses.
**Parameters:**
- `from_name` through `from_zip`: Sender address details
- `to_name` through `to_zip`: Recipient address details
- `length`, `width`, `height`: Package dimensions
- `weight`: Package weight
- `from_country`, `to_country` (optional): Country codes (default: "US")
- `distance_unit` (optional): "in" or "cm" (default: "in")
- `mass_unit` (optional): "lb" or "kg" (default: "lb")
##### 3. `create_shipment`
Create a shipment and get basic information about available rates.
**Parameters:** Same as `get_shipping_rates`
##### 4. `list_shipments`
List all shipments for the account with summary information.
**Parameters:** None
##### 5. `get_shipment`
Get detailed information about a specific shipment, including all available rates.
**Parameters:**
- `shipment_id` (required): The ID of the shipment to retrieve
#### Labels & Transactions
##### 6. `create_shipping_label`
Create a shipping label from a rate ID.
**Parameters:**
- `rate_id` (required): The ID of the rate to purchase (obtained from `get_shipping_rates` or `get_shipment`)
##### 7. `list_transactions`
List all shipping label transactions to find transaction IDs for refunds.
**Parameters:** None
#### Refunds
##### 8. `create_refund`
Create a refund for a shipping label transaction.
**Parameters:**
- `transaction_id` (required): The ID of the transaction to refund (obtained from `list_transactions`)
##### 9. `list_refunds`
List all refunds for the account with detailed status information and visual indicators.
**Parameters:** None
##### 10. `get_refund`
Get comprehensive details of a specific refund including status, dates, and transaction info.
**Parameters:**
- `refund_id` (required): The ID of the refund to retrieve
#### Tracking & Management
##### 11. `track_package`
Track a package using its tracking number.
**Parameters:**
- `tracking_number` (required): The tracking number
- `carrier` (required): Carrier name (e.g., "usps", "ups", "fedex")
##### 12. `list_carrier_accounts`
List all configured carrier accounts in your Shippo account.
**Parameters:** None
## Example Workflows
### 1. Getting Shipping Quotes
```
1. Use `validate_address` for both sender and recipient addresses
2. Confirm package dimensions and weight with user
3. Use `get_shipping_rates` to get all available options
4. Present rates clearly to user for selection
```
### 2. Complete Shipping Process
```
1. Validate sender and recipient addresses
2. Confirm package dimensions and weight
3. Use `get_shipping_rates` to get available options
4. Present rates and ask user to select preferred option
5. Use `create_shipping_label` with chosen rate_id
6. Provide label URL and tracking information to user
```
### 3. Managing Existing Shipments
```
1. Use `list_shipments` to see all shipments and their IDs
2. Use `get_shipment` with specific shipment ID for detailed info
3. Use rate IDs from `get_shipment` to create labels with `create_shipping_label`
```
### 4. Refund Management
```
1. Use `list_transactions` to find the transaction ID for a purchased label
2. Use `create_refund` with the transaction ID to request a refund
3. Use `list_refunds` to see all refunds with status indicators
4. Use `get_refund` for detailed status and explanations
```
### 5. Package Tracking
```
1. Get tracking number from shipping label creation
2. Use `track_package` with tracking number and carrier
3. Monitor delivery status and history
```
## Supported Carriers
Shippo supports many carriers including:
- USPS
- UPS
- FedEx
- DHL
- Canada Post
- Australia Post
- And many more regional carriers
The available carriers depend on your Shippo account configuration and carrier accounts you've set up.
## Development
### Project Structure
```
shippo-mcp/
├── server.py # Main MCP server implementation
├── pyproject.toml # Python dependencies and project config
└── readme.md # This file
```
### Testing
To test individual tools:
1. Start the server
2. Use an MCP client or test the functions directly
3. Use Shippo's test API keys to avoid charges
### Error Handling
The server includes comprehensive error handling for:
- Missing API keys
- Invalid addresses
- Network issues
- Shippo API errors
- Invalid parameters
## Security Notes
- Never commit your actual API keys to version control
- Use test API keys for development
- Live API keys will charge real money for label purchases
- Store API keys securely in production environments
## API Rate Limits
Shippo has rate limits on their API. The server handles basic error cases, but for high-volume usage, consider implementing additional rate limiting or retry logic.
## Support
- [Shippo Documentation](https://docs.goshippo.com/)
- [Shippo API Reference](https://docs.goshippo.com/docs/reference)
- [MCP Protocol Documentation](https://modelcontextprotocol.io/)
## License
This project is open source. See the license terms in your repository for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "shippo-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Foad Kesheh",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/40/0b/d313a9871b7840ea358699a38e2a2c3babceae03ef8a20349c07fa1a67b0/shippo_mcp-0.1.2.tar.gz",
"platform": null,
"description": "# Shippo MCP Server\n\nA Model Context Protocol (MCP) server that integrates with the [Shippo shipping API](https://goshippo.com/) to provide shipping functionality through an AI assistant. This server enables you to validate addresses, get shipping rates, create shipments, generate shipping labels, track packages, manage carrier accounts, and handle refunds.\n\n## Features\n\n- **Address Validation**: Validate shipping addresses using Shippo's address validation service\n- **Shipping Rates**: Get real-time shipping rates from multiple carriers\n- **Shipment Management**: Create, list, and retrieve detailed shipment information\n- **Label Creation**: Generate shipping labels for packages\n- **Transaction Management**: List and manage shipping label transactions\n- **Refund Processing**: Create and track refunds for shipping labels\n- **Package Tracking**: Track packages using tracking numbers\n- **Carrier Management**: List and manage configured carrier accounts\n\n## Prerequisites\n\n1. **Homebrew** (macOS/Linux): Install from [brew.sh](https://brew.sh/)\n ```bash\n /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n ```\n\n2. **uv** (Python package manager): Install via Homebrew\n ```bash\n brew install uv\n ```\n\n3. **Python 3.13+**: This project requires Python 3.13 or higher (uv will handle this)\n\n4. **Shippo Account**: Sign up for a free [Shippo account](https://apps.goshippo.com/join)\n\n5. **API Key**: Generate an [API Token](https://docs.goshippo.com/docs/guides_general/authentication/) from your Shippo dashboard\n\n## Installation\n\n1. Clone or download this repository\n2. Install dependencies using uv:\n ```bash\n uv install\n ```\n\n## Configuration\n\nThe server gets the Shippo API key from environment variables. You can set it either:\n\n1. **Via MCP client configuration** (recommended for production)\n2. **Via command line** for testing:\n ```bash\n export SHIPPO_API_KEY=shippo_test_your_api_key_here\n ```\n\n> **Note**: Use a test API key (starts with `shippo_test_`) for development and testing. Only use live API keys for production.\n\n## Usage\n\n### Starting the Server\n\n#### For stdio transport (MCP client integration)\n```bash\nexport SHIPPO_API_KEY=shippo_test_your_api_key_here && uv run --with shippo-mcp shippo-mcp stdio\n```\n\n#### For HTTP transport (Inspector compatible)\n```bash\nexport SHIPPO_API_KEY=shippo_test_your_api_key_here && uv run --with shippo-mcp shippo-mcp server\n```\nThe server will be available at: http://127.0.0.1:8000/mcp\n\n### Getting Help\n```bash\nuv run --with shippo-mcp shippo-mcp --help\n```\n\n### MCP Client Configuration\n\n#### Claude Desktop Configuration\n\nAdd this configuration to your Claude Desktop config file (usually located at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n \"mcpServers\": {\n \"shippo\": {\n \"command\": \"/opt/homebrew/bin/uv\",\n \"args\": [\n \"run\",\n \"--with\",\n \"shippo-mcp\",\n \"shippo-mcp\",\n \"stdio\"\n ],\n \"env\": {\n \"SHIPPO_API_KEY\": \"shippo_test_your_api_key_here\"\n }\n }\n }\n}\n```\n\n### Available Tools\n\n#### Address & Validation\n\n##### 1. `validate_address`\nValidate a shipping address to ensure it's deliverable.\n\n**Parameters:**\n- `name` (required): Recipient name\n- `street1` (required): Primary street address\n- `city` (required): City name\n- `state` (required): State/province code\n- `zip_code` (required): ZIP/postal code\n- `country` (optional): Country code (default: \"US\")\n- `street2` (optional): Secondary address line\n- `company` (optional): Company name\n- `phone` (optional): Phone number\n- `email` (optional): Email address\n\n#### Rates & Shipping\n\n##### 2. `get_shipping_rates`\nGet shipping rates for a package between two addresses.\n\n**Parameters:**\n- `from_name` through `from_zip`: Sender address details\n- `to_name` through `to_zip`: Recipient address details\n- `length`, `width`, `height`: Package dimensions\n- `weight`: Package weight\n- `from_country`, `to_country` (optional): Country codes (default: \"US\")\n- `distance_unit` (optional): \"in\" or \"cm\" (default: \"in\")\n- `mass_unit` (optional): \"lb\" or \"kg\" (default: \"lb\")\n\n##### 3. `create_shipment`\nCreate a shipment and get basic information about available rates.\n\n**Parameters:** Same as `get_shipping_rates`\n\n##### 4. `list_shipments`\nList all shipments for the account with summary information.\n\n**Parameters:** None\n\n##### 5. `get_shipment`\nGet detailed information about a specific shipment, including all available rates.\n\n**Parameters:**\n- `shipment_id` (required): The ID of the shipment to retrieve\n\n#### Labels & Transactions\n\n##### 6. `create_shipping_label`\nCreate a shipping label from a rate ID.\n\n**Parameters:**\n- `rate_id` (required): The ID of the rate to purchase (obtained from `get_shipping_rates` or `get_shipment`)\n\n##### 7. `list_transactions`\nList all shipping label transactions to find transaction IDs for refunds.\n\n**Parameters:** None\n\n#### Refunds\n\n##### 8. `create_refund`\nCreate a refund for a shipping label transaction.\n\n**Parameters:**\n- `transaction_id` (required): The ID of the transaction to refund (obtained from `list_transactions`)\n\n##### 9. `list_refunds`\nList all refunds for the account with detailed status information and visual indicators.\n\n**Parameters:** None\n\n##### 10. `get_refund`\nGet comprehensive details of a specific refund including status, dates, and transaction info.\n\n**Parameters:**\n- `refund_id` (required): The ID of the refund to retrieve\n\n#### Tracking & Management\n\n##### 11. `track_package`\nTrack a package using its tracking number.\n\n**Parameters:**\n- `tracking_number` (required): The tracking number\n- `carrier` (required): Carrier name (e.g., \"usps\", \"ups\", \"fedex\")\n\n##### 12. `list_carrier_accounts`\nList all configured carrier accounts in your Shippo account.\n\n**Parameters:** None\n\n## Example Workflows\n\n### 1. Getting Shipping Quotes\n```\n1. Use `validate_address` for both sender and recipient addresses\n2. Confirm package dimensions and weight with user\n3. Use `get_shipping_rates` to get all available options\n4. Present rates clearly to user for selection\n```\n\n### 2. Complete Shipping Process\n```\n1. Validate sender and recipient addresses\n2. Confirm package dimensions and weight\n3. Use `get_shipping_rates` to get available options\n4. Present rates and ask user to select preferred option\n5. Use `create_shipping_label` with chosen rate_id\n6. Provide label URL and tracking information to user\n```\n\n### 3. Managing Existing Shipments\n```\n1. Use `list_shipments` to see all shipments and their IDs\n2. Use `get_shipment` with specific shipment ID for detailed info\n3. Use rate IDs from `get_shipment` to create labels with `create_shipping_label`\n```\n\n### 4. Refund Management\n```\n1. Use `list_transactions` to find the transaction ID for a purchased label\n2. Use `create_refund` with the transaction ID to request a refund\n3. Use `list_refunds` to see all refunds with status indicators\n4. Use `get_refund` for detailed status and explanations\n```\n\n### 5. Package Tracking\n```\n1. Get tracking number from shipping label creation\n2. Use `track_package` with tracking number and carrier\n3. Monitor delivery status and history\n```\n\n## Supported Carriers\n\nShippo supports many carriers including:\n- USPS\n- UPS\n- FedEx\n- DHL\n- Canada Post\n- Australia Post\n- And many more regional carriers\n\nThe available carriers depend on your Shippo account configuration and carrier accounts you've set up.\n\n## Development\n\n### Project Structure\n```\nshippo-mcp/\n\u251c\u2500\u2500 server.py # Main MCP server implementation\n\u251c\u2500\u2500 pyproject.toml # Python dependencies and project config\n\u2514\u2500\u2500 readme.md # This file\n```\n\n### Testing\n\nTo test individual tools:\n\n1. Start the server\n2. Use an MCP client or test the functions directly\n3. Use Shippo's test API keys to avoid charges\n\n### Error Handling\n\nThe server includes comprehensive error handling for:\n- Missing API keys\n- Invalid addresses\n- Network issues\n- Shippo API errors\n- Invalid parameters\n\n## Security Notes\n\n- Never commit your actual API keys to version control\n- Use test API keys for development\n- Live API keys will charge real money for label purchases\n- Store API keys securely in production environments\n\n## API Rate Limits\n\nShippo has rate limits on their API. The server handles basic error cases, but for high-volume usage, consider implementing additional rate limiting or retry logic.\n\n## Support\n\n- [Shippo Documentation](https://docs.goshippo.com/)\n- [Shippo API Reference](https://docs.goshippo.com/docs/reference)\n- [MCP Protocol Documentation](https://modelcontextprotocol.io/)\n\n## License\n\nThis project is open source. See the license terms in your repository for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An unofficial MCP server for Shippo shipping API integration",
"version": "0.1.2",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f0ca548586ab83c87c4a09cc35002b34768e157d892aefdd46c757bf14737625",
"md5": "f6fccd12fbdbeae62ad4e6ea3b6670d3",
"sha256": "be8052f9831506dc91b0626a4c0ec2bc4fc15fc4e49cbe0fcf9dcda6adf4ccd8"
},
"downloads": -1,
"filename": "shippo_mcp-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f6fccd12fbdbeae62ad4e6ea3b6670d3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 16757,
"upload_time": "2025-07-16T21:17:59",
"upload_time_iso_8601": "2025-07-16T21:17:59.401821Z",
"url": "https://files.pythonhosted.org/packages/f0/ca/548586ab83c87c4a09cc35002b34768e157d892aefdd46c757bf14737625/shippo_mcp-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "400bd313a9871b7840ea358699a38e2a2c3babceae03ef8a20349c07fa1a67b0",
"md5": "32a167037e302621ed3bd088e24a8b1b",
"sha256": "cf679f944654dbc8da0fa981608683b9c7e483c2a909f22e297636865377fa4f"
},
"downloads": -1,
"filename": "shippo_mcp-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "32a167037e302621ed3bd088e24a8b1b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 42846,
"upload_time": "2025-07-16T21:18:01",
"upload_time_iso_8601": "2025-07-16T21:18:01.734152Z",
"url": "https://files.pythonhosted.org/packages/40/0b/d313a9871b7840ea358699a38e2a2c3babceae03ef8a20349c07fa1a67b0/shippo_mcp-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 21:18:01",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "shippo-mcp"
}
