# ShipBoss MCP Server
An MCP server that provides shipping and logistics capabilities through AI conversations. Connect to FedEx, UPS, and DHL to get rates, create labels, track packages, and manage freight shipments.
> **🔑 Important**: You'll need a ShipBoss API token to use this server. Get one from your [ShipBoss Admin → API Integrations](https://ship.shipboss.io/customer-admin/api-integrations).
## 🚀 Quick Setup (5 Minutes)
### Prerequisites
- **Python 3.9+** installed
- **ShipBoss account** with API token (get one in the admin section at [ship.shipboss.io](https://ship.shipboss.io))
### Step-by-Step Installation
**Step 1: Get Your ShipBoss API Token** 🔑
This is required for the server to communicate with ShipBoss APIs.
1. Go to [ShipBoss](https://ship.shipboss.io) and log in
2. Navigate to your Admin section → [API Integrations](https://ship.shipboss.io/customer-admin/api-integrations)
3. Generate a new API token and copy it
4. **Keep this token secure** - you'll need it in the next step
**Step 2: Create a Virtual Environment** 🐍
Using a virtual environment is **required** to avoid dependency conflicts with your system Python installation.
```bash
# Create a virtual environment
python -m venv shipboss_env
# Activate it
# Windows:
shipboss_env\Scripts\activate
# macOS/Linux:
source shipboss_env/bin/activate
# Install the package
pip install shipboss-mcp-server
```
**⚠️ Important**: Do **NOT** install directly with `pip install shipboss-mcp-server` without a virtual environment. This can cause conflicts with your system Python packages.
**Step 3: Configure API Token & MCP Server** 🔑
The server needs your API token to authenticate with ShipBoss. **Important**: The MCP configuration depends on how you installed the server.
### For Pip Installation (Recommended)
If you installed via `pip install shipboss-mcp-server`:
#### Option A: .env File (Simplest - Automatic) 📁
```bash
# Create environment file in your working directory (where you'll run your MCP client)
echo "SHIPBOSS_API_TOKEN=your_api_token_here" > .env
# Or use the provided template
cp example.env .env # Then edit .env with your actual token
```
Then use this configuration:
```json
{
"mcpServers": {
"shipboss-mcp": {
"command": "shipboss-mcp-server"
}
}
}
```
#### Option B: Command-Line Arguments
```json
{
"mcpServers": {
"shipboss-mcp": {
"command": "shipboss-mcp-server",
"args": ["--api-token", "your_api_token_here"]
}
}
}
```
#### Option C: Environment Variable
```json
{
"mcpServers": {
"shipboss-mcp": {
"command": "shipboss-mcp-server",
"env": {
"SHIPBOSS_API_TOKEN": "your_api_token_here"
}
}
}
}
```
### For Local Development (Alternative)
If you cloned the repository and want to run from source:
#### Option A: .env File (Simplest - Automatic) 📁
```bash
# Create environment file in the project directory
echo "SHIPBOSS_API_TOKEN=your_api_token_here" > .env
```
Then use this configuration:
```json
{
"mcpServers": {
"shipboss-mcp": {
"command": "C:\\path\\to\\shipboss_env\\Scripts\\python.exe",
"args": ["C:\\path\\to\\shipboss-mcp\\shipboss_mcp_server.py"]
}
}
}
```
#### Option B: Command-Line Arguments
```json
{
"mcpServers": {
"shipboss-mcp": {
"command": "C:\\path\\to\\shipboss_env\\Scripts\\python.exe",
"args": [
"C:\\path\\to\\shipboss-mcp\\shipboss_mcp_server.py",
"--api-token", "your_api_token_here"
]
}
}
}
```
#### Option C: Environment Variable
```json
{
"mcpServers": {
"shipboss-mcp": {
"command": "C:\\path\\to\\shipboss_env\\Scripts\\python.exe",
"args": ["C:\\path\\to\\shipboss-mcp\\shipboss_mcp_server.py"],
"env": {
"SHIPBOSS_API_TOKEN": "your_api_token_here"
}
}
}
}
```
**Step 4: Test Your Setup** 🧪
Make sure your virtual environment is activated, then restart your MCP client and try these commands:
- *"Get shipping rates from New York to Los Angeles for a 2lb package"*
- *"Create a FedEx Ground label from 123 Main St, New York, NY to 456 Oak Ave, Los Angeles, CA"*
**Quick verification**: Before restarting your MCP client, test the server directly:
```bash
# Make sure your virtual environment is activated first
# Windows: shipboss_env\Scripts\activate
# macOS/Linux: source shipboss_env/bin/activate
# Test with your API token
shipboss-mcp-server --api-token your_actual_token_here
# Should start without "API token required" error
```
## Available Tools
- **ping** - Health check
- **get_parcel_rates** - Get parcel shipping rates
- **create_parcel_label** - Create parcel shipping labels with direct download URLs
- **track_parcel** - Track parcel shipments
- **create_pickup** - Schedule carrier pickups
- **cancel_pickup** - Cancel scheduled pickups
- **get_freight_rates** - Get freight shipping quotes
- **track_freight** - Track freight shipments
## Troubleshooting
### Common Issues:
1. **"shipboss-mcp-server command not found"** ❌: Make sure your virtual environment is activated before running the command.
- **Solution**: Activate your virtual environment first:
```bash
# Windows: shipboss_env\Scripts\activate
# macOS/Linux: source shipboss_env/bin/activate
```
2. **"API token required" error** 🔐: Make sure you have your API token configured using one of these methods:
- **Easiest**: Create a `.env` file with `SHIPBOSS_API_TOKEN=your_token` (automatically loaded)
- Add `--api-token your_token` to the args in your MCP config
- Set `SHIPBOSS_API_TOKEN` in the env section of your MCP config
- **Verify your token**: Make sure it's from [ShipBoss API Integrations](https://ship.shipboss.io/customer-admin/api-integrations)
2. **".env file not found"**: The `.env` file should be in your current working directory when running the `shipboss-mcp-server` command.
- Check if the file exists: `ls -la .env`
- Verify the token format: `cat .env` (should show `SHIPBOSS_API_TOKEN=your_token_here`)
3. **"Unexpected token" errors**: Make sure the package is properly installed with `pip install shipboss-mcp-server`.
4. **Command not found**: Ensure the package is installed and the `shipboss-mcp-server` command is available in your PATH.
5. **Permission errors**: The installed package should have proper permissions. Try running with `python -m shipboss_mcp_server` if the command fails.
### Debug Mode:
Run the server directly to test:
```bash
# Using the installed command:
shipboss-mcp-server --api-token your_token
# Or using python module:
python -m shipboss_mcp_server --api-token your_token
```
Raw data
{
"_id": null,
"home_page": null,
"name": "shipboss-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "shipping, mcp, shipboss, fastmcp",
"author": null,
"author_email": "ShipBoss <support@shipboss.io>",
"download_url": "https://files.pythonhosted.org/packages/02/15/85592520c05fb01557bc70e598f7f97956c00b93eb9e34e04cf65af8c45a/shipboss_mcp_server-4.0.10.tar.gz",
"platform": null,
"description": "# ShipBoss MCP Server\r\n\r\nAn MCP server that provides shipping and logistics capabilities through AI conversations. Connect to FedEx, UPS, and DHL to get rates, create labels, track packages, and manage freight shipments.\r\n\r\n> **\ud83d\udd11 Important**: You'll need a ShipBoss API token to use this server. Get one from your [ShipBoss Admin \u2192 API Integrations](https://ship.shipboss.io/customer-admin/api-integrations).\r\n\r\n## \ud83d\ude80 Quick Setup (5 Minutes)\r\n\r\n### Prerequisites\r\n- **Python 3.9+** installed\r\n- **ShipBoss account** with API token (get one in the admin section at [ship.shipboss.io](https://ship.shipboss.io))\r\n\r\n### Step-by-Step Installation\r\n\r\n**Step 1: Get Your ShipBoss API Token** \ud83d\udd11\r\nThis is required for the server to communicate with ShipBoss APIs.\r\n\r\n1. Go to [ShipBoss](https://ship.shipboss.io) and log in\r\n2. Navigate to your Admin section \u2192 [API Integrations](https://ship.shipboss.io/customer-admin/api-integrations)\r\n3. Generate a new API token and copy it\r\n4. **Keep this token secure** - you'll need it in the next step\r\n\r\n**Step 2: Create a Virtual Environment** \ud83d\udc0d\r\nUsing a virtual environment is **required** to avoid dependency conflicts with your system Python installation.\r\n\r\n```bash\r\n# Create a virtual environment\r\npython -m venv shipboss_env\r\n\r\n# Activate it\r\n# Windows:\r\nshipboss_env\\Scripts\\activate\r\n# macOS/Linux:\r\nsource shipboss_env/bin/activate\r\n\r\n# Install the package\r\npip install shipboss-mcp-server\r\n```\r\n\r\n**\u26a0\ufe0f Important**: Do **NOT** install directly with `pip install shipboss-mcp-server` without a virtual environment. This can cause conflicts with your system Python packages.\r\n\r\n**Step 3: Configure API Token & MCP Server** \ud83d\udd11\r\n\r\nThe server needs your API token to authenticate with ShipBoss. **Important**: The MCP configuration depends on how you installed the server.\r\n\r\n### For Pip Installation (Recommended)\r\nIf you installed via `pip install shipboss-mcp-server`:\r\n\r\n#### Option A: .env File (Simplest - Automatic) \ud83d\udcc1\r\n```bash\r\n# Create environment file in your working directory (where you'll run your MCP client)\r\necho \"SHIPBOSS_API_TOKEN=your_api_token_here\" > .env\r\n\r\n# Or use the provided template\r\ncp example.env .env # Then edit .env with your actual token\r\n```\r\n\r\nThen use this configuration:\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"shipboss-mcp\": {\r\n \"command\": \"shipboss-mcp-server\"\r\n }\r\n }\r\n}\r\n```\r\n\r\n#### Option B: Command-Line Arguments\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"shipboss-mcp\": {\r\n \"command\": \"shipboss-mcp-server\",\r\n \"args\": [\"--api-token\", \"your_api_token_here\"]\r\n }\r\n }\r\n}\r\n```\r\n\r\n#### Option C: Environment Variable\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"shipboss-mcp\": {\r\n \"command\": \"shipboss-mcp-server\",\r\n \"env\": {\r\n \"SHIPBOSS_API_TOKEN\": \"your_api_token_here\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\n### For Local Development (Alternative)\r\nIf you cloned the repository and want to run from source:\r\n\r\n#### Option A: .env File (Simplest - Automatic) \ud83d\udcc1\r\n```bash\r\n# Create environment file in the project directory\r\necho \"SHIPBOSS_API_TOKEN=your_api_token_here\" > .env\r\n```\r\n\r\nThen use this configuration:\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"shipboss-mcp\": {\r\n \"command\": \"C:\\\\path\\\\to\\\\shipboss_env\\\\Scripts\\\\python.exe\",\r\n \"args\": [\"C:\\\\path\\\\to\\\\shipboss-mcp\\\\shipboss_mcp_server.py\"]\r\n }\r\n }\r\n}\r\n```\r\n\r\n#### Option B: Command-Line Arguments\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"shipboss-mcp\": {\r\n \"command\": \"C:\\\\path\\\\to\\\\shipboss_env\\\\Scripts\\\\python.exe\",\r\n \"args\": [\r\n \"C:\\\\path\\\\to\\\\shipboss-mcp\\\\shipboss_mcp_server.py\",\r\n \"--api-token\", \"your_api_token_here\"\r\n ]\r\n }\r\n }\r\n}\r\n```\r\n\r\n#### Option C: Environment Variable\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"shipboss-mcp\": {\r\n \"command\": \"C:\\\\path\\\\to\\\\shipboss_env\\\\Scripts\\\\python.exe\",\r\n \"args\": [\"C:\\\\path\\\\to\\\\shipboss-mcp\\\\shipboss_mcp_server.py\"],\r\n \"env\": {\r\n \"SHIPBOSS_API_TOKEN\": \"your_api_token_here\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\n\r\n\r\n**Step 4: Test Your Setup** \ud83e\uddea\r\nMake sure your virtual environment is activated, then restart your MCP client and try these commands:\r\n- *\"Get shipping rates from New York to Los Angeles for a 2lb package\"*\r\n- *\"Create a FedEx Ground label from 123 Main St, New York, NY to 456 Oak Ave, Los Angeles, CA\"*\r\n\r\n**Quick verification**: Before restarting your MCP client, test the server directly:\r\n```bash\r\n# Make sure your virtual environment is activated first\r\n# Windows: shipboss_env\\Scripts\\activate\r\n# macOS/Linux: source shipboss_env/bin/activate\r\n\r\n# Test with your API token\r\nshipboss-mcp-server --api-token your_actual_token_here\r\n# Should start without \"API token required\" error\r\n```\r\n\r\n## Available Tools\r\n\r\n- **ping** - Health check\r\n- **get_parcel_rates** - Get parcel shipping rates\r\n- **create_parcel_label** - Create parcel shipping labels with direct download URLs\r\n- **track_parcel** - Track parcel shipments\r\n- **create_pickup** - Schedule carrier pickups\r\n- **cancel_pickup** - Cancel scheduled pickups\r\n- **get_freight_rates** - Get freight shipping quotes\r\n- **track_freight** - Track freight shipments\r\n\r\n## Troubleshooting\r\n\r\n### Common Issues:\r\n\r\n1. **\"shipboss-mcp-server command not found\"** \u274c: Make sure your virtual environment is activated before running the command.\r\n - **Solution**: Activate your virtual environment first:\r\n ```bash\r\n # Windows: shipboss_env\\Scripts\\activate\r\n # macOS/Linux: source shipboss_env/bin/activate\r\n ```\r\n\r\n2. **\"API token required\" error** \ud83d\udd10: Make sure you have your API token configured using one of these methods:\r\n - **Easiest**: Create a `.env` file with `SHIPBOSS_API_TOKEN=your_token` (automatically loaded)\r\n - Add `--api-token your_token` to the args in your MCP config\r\n - Set `SHIPBOSS_API_TOKEN` in the env section of your MCP config\r\n - **Verify your token**: Make sure it's from [ShipBoss API Integrations](https://ship.shipboss.io/customer-admin/api-integrations)\r\n\r\n2. **\".env file not found\"**: The `.env` file should be in your current working directory when running the `shipboss-mcp-server` command.\r\n - Check if the file exists: `ls -la .env`\r\n - Verify the token format: `cat .env` (should show `SHIPBOSS_API_TOKEN=your_token_here`)\r\n\r\n3. **\"Unexpected token\" errors**: Make sure the package is properly installed with `pip install shipboss-mcp-server`.\r\n\r\n4. **Command not found**: Ensure the package is installed and the `shipboss-mcp-server` command is available in your PATH.\r\n\r\n5. **Permission errors**: The installed package should have proper permissions. Try running with `python -m shipboss_mcp_server` if the command fails.\r\n\r\n### Debug Mode:\r\nRun the server directly to test:\r\n```bash\r\n# Using the installed command:\r\nshipboss-mcp-server --api-token your_token\r\n\r\n# Or using python module:\r\npython -m shipboss_mcp_server --api-token your_token\r\n```\r\n",
"bugtrack_url": null,
"license": null,
"summary": "ShipBoss MCP server with parcel & freight endpoints",
"version": "4.0.10",
"project_urls": null,
"split_keywords": [
"shipping",
" mcp",
" shipboss",
" fastmcp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "55d499047c782d1792896d824e349e49ddde0047fb3452cb276179def906e7d4",
"md5": "6dd1c5c39d1d544e5af0c99b44458848",
"sha256": "66ad43c38482e6742dab78464af214793f9e698b059943e5c458246e73b734f5"
},
"downloads": -1,
"filename": "shipboss_mcp_server-4.0.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6dd1c5c39d1d544e5af0c99b44458848",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 10783,
"upload_time": "2025-08-24T13:48:29",
"upload_time_iso_8601": "2025-08-24T13:48:29.512501Z",
"url": "https://files.pythonhosted.org/packages/55/d4/99047c782d1792896d824e349e49ddde0047fb3452cb276179def906e7d4/shipboss_mcp_server-4.0.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "021585592520c05fb01557bc70e598f7f97956c00b93eb9e34e04cf65af8c45a",
"md5": "6f7f4e1748b6aedaaf7ef5a7020fc90d",
"sha256": "3009e763f1c4dc5c6de1a9d22599a039940a995d8eecbdcba89f0360d46e1180"
},
"downloads": -1,
"filename": "shipboss_mcp_server-4.0.10.tar.gz",
"has_sig": false,
"md5_digest": "6f7f4e1748b6aedaaf7ef5a7020fc90d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 10638,
"upload_time": "2025-08-24T13:48:31",
"upload_time_iso_8601": "2025-08-24T13:48:31.566251Z",
"url": "https://files.pythonhosted.org/packages/02/15/85592520c05fb01557bc70e598f7f97956c00b93eb9e34e04cf65af8c45a/shipboss_mcp_server-4.0.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-24 13:48:31",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "shipboss-mcp-server"
}
JSON