# MCP Server ## Overview The Shippo MCP (Model Context Protocol) Server enables AI assistants and LLMs to interact directly with the Shippo API through a standardized interface. This allows AI-powered applications to create shipments, generate labels, track packages, and manage shipping operations seamlessly. ## What is MCP? Model Context Protocol (MCP) is an open protocol developed by Anthropic that standardizes how AI applications communicate with external data sources and tools. The Shippo MCP Server implements this protocol, making Shippo's shipping capabilities accessible to AI assistants like Claude, Cursor, and other MCP-compatible clients. ## Features The Shippo MCP Server provides access to core Shippo API functionality: ### Address Management - **Validate Addresses**: Verify and standardize shipping addresses - **Create Address Records**: Store addresses for future use - **Address Book**: Manage sender and recipient addresses ### Shipping Operations - **Create Shipments**: Set up shipments with origin, destination, and parcel details - **Get Rates**: Compare shipping rates across multiple carriers - **Generate Labels**: Purchase shipping labels for your shipments - **Track Packages**: Monitor shipment status and location ### Carrier Accounts - **List Carrier Accounts**: View all connected carrier accounts - **Manage Carriers**: Add or update carrier account settings - **Multi-Carrier Support**: Works with USPS, UPS, FedEx, DHL, and more ### International Shipping - **Customs Declarations**: Create customs documentation for international shipments - **Customs Items**: Define items for customs processing - **Multi-Country Support**: Ship internationally with proper documentation ### Advanced Features - **Batch Operations**: Process multiple shipments at once - **Pickups**: Schedule carrier pickups - **Manifests**: Generate end-of-day manifests - **Webhooks**: Set up event notifications ## Getting Started ### Prerequisites - [Node.js](https://nodejs.org/) v18+ - A Shippo account ([sign up here](https://goshippo.com/) — it's free!) - Your Shippo API token - An MCP-compatible client (Cursor, Claude Desktop, or other MCP clients) ### Get Your API Key 1. Sign up or log in at [goshippo.com](https://goshippo.com) 2. Navigate to [API Settings](https://apps.goshippo.com/api) 3. Generate a new API key 4. Copy the key for use in your MCP configuration > **Tip**: Use test API keys (starting with `shippo_test_`) during development. Test labels are free — you only pay when printing live labels. **Important**: When configuring the server, you must include the `ShippoToken` prefix before your key (e.g., `ShippoToken shippo_test_...`). ## Installation Choose your preferred MCP client below: ### Cursor The easiest way to install is using the one-click installer: [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=shippo-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzaGlwcG8vc2hpcHBvLW1jcCIsInN0YXJ0IiwiLS1hcGkta2V5LWhlYWRlciIsIlNoaXBwb1Rva2VuIFlPVVJfU0hJUFBPX0FQSV9LRVkiLCItLXNoaXBwby1hcGktdmVyc2lvbiIsIjIwMTgtMDItMDgiXX0=) > ⚠️ **Important**: Click **Install** first to add the server. Then, go to **Settings → Tools & MCP → shippo-mcp (edit)** to edit the configuration. Replace `YOUR_SHIPPO_API_KEY` with your actual API key (ensure you keep or add the `ShippoToken ` prefix), then save `mcp.json`. You may need to toggle the server off and on for changes to take effect. #### Manual Cursor Installation 1. Open **Cursor Settings** 2. Select **Tools and Integrations** 3. Click **New MCP Server** 4. Paste the following configuration: ```json { "mcpServers": { "shippo-mcp": { "command": "npx", "args": [ "-y", "@shippo/shippo-mcp", "start", "--api-key-header", "ShippoToken YOUR_SHIPPO_API_KEY", "--shippo-api-version", "2018-02-08" ] } } } ``` 1. Replace `YOUR_SHIPPO_API_KEY` with your actual API key (keeping the `ShippoToken` prefix) 2. Save and restart Cursor ### Claude Desktop 1. Open Claude Desktop 2. Click on your **Username** in the left sidebar 3. Go to **Settings** 4. Select the **Developer** tab 5. Click **Edit Config** 6. Add the Shippo MCP Server configuration: ```json { "mcpServers": { "shippo-mcp": { "command": "npx", "args": [ "-y", "@shippo/shippo-mcp", "start", "--api-key-header", "ShippoToken YOUR_SHIPPO_API_KEY", "--shippo-api-version", "2018-02-08" ] } } } ``` 1. Replace `YOUR_SHIPPO_API_KEY` with your actual API key (keeping the `ShippoToken` prefix) 2. Save and restart Claude Desktop ### Claude Code CLI ```bash claude mcp add shippo-mcp -- npx -y @shippo/shippo-mcp start --api-key-header "ShippoToken YOUR_SHIPPO_API_KEY" --shippo-api-version 2018-02-08 ``` ### Command Line Run the MCP server directly (useful for debugging or manual connections): ```bash npx -y @shippo/shippo-mcp start --api-key-header "ShippoToken YOUR_SHIPPO_API_KEY" --shippo-api-version 2018-02-08 ``` > **Note:** This starts the server in stdio mode, waiting for MCP protocol messages. It won't show an interactive prompt — it's designed to be connected to by an MCP client like Cursor or Claude Desktop. For a full list of server arguments: ```bash npx @shippo/shippo-mcp --help ``` ## Usage Examples Once configured, you can interact with Shippo through natural language: ### Create a Shipping Label ``` Create a shipping label from: 123 Main St, San Francisco, CA 94105 To: 456 Market St, New York, NY 10001 Package dimensions: 10x8x6 inches, 2 lbs ``` ### Track a Package ``` Track package with tracking number: 1Z999AA10123456784 ``` ### Validate an Address ``` Validate this address: 215 Clayton St, San Francisco, CA 94117 ``` ### Compare Shipping Rates ``` Get shipping rates for a 5lb package (12x10x8 inches) from Los Angeles, CA 90001 to Chicago, IL 60601 ``` ## Updating The MCP server is distributed via npm. To ensure you have the latest features and bug fixes, update periodically. ### Check Current Version ```bash npx @shippo/shippo-mcp --version ``` ### Update to Latest Version ```bash npm update -g @shippo/shippo-mcp ``` Next time you start your MCP client (Cursor, Claude), it will fetch the latest version. > **Tip:** After updating, toggle your MCP server off and on in Cursor/Claude settings for changes to take effect. details summary Development To build the MCP server from source: 1. Clone the repository 2. Install dependencies: ```bash npm install ``` 3. Build the server: ```bash npm run build ``` 4. The server binary will be at `bin/mcp-server.js` ### Local Development Configuration To run the server locally from source, use this configuration: ```json { "mcpServers": { "shippo-dev": { "command": "node", "args": [ "/ABSOLUTE/PATH/TO/REPO/bin/mcp-server.js", "start", "--api-key-header", "ShippoToken YOUR_SHIPPO_API_KEY", "--shippo-api-version", "2018-02-08" ] } } } ``` Replace `/ABSOLUTE/PATH/TO/REPO` with the full path to your cloned repository. ## Testing The Shippo MCP Server supports Shippo's test mode. When using test API tokens (those starting with `shippo_test_`), all operations will use test mode and won't create real shipments or charges. **Test mode benefits:** - Free test labels - No charges to your account - Safe experimentation - Full API functionality ## Security ### API Key Management | Key Type | Prefix | Use Case | | --- | --- | --- | | **Test Keys** | `shippo_test_` | Development, testing, demos | | **Live Keys** | `shippo_live_` | Production only | ### Best Practices - **Never commit** API keys to source control - **Use test keys** during development - **Rotate keys** regularly for security - **Never share** keys publicly - **Store keys** in environment variables or secure credential stores ### Environment Variables For added security, you can store your API key in an environment variable: ```bash # Add to ~/.zshrc or ~/.bashrc export SHIPPO_API_KEY="your_api_key_here" ``` Then reference it in your configuration as needed. ## Resources - [Shippo API Documentation](/) - [Quickstart Guide](/docs/guides_general/api_quickstart) - [Authentication](/docs/guides_general/authentication) - [MCP Protocol Specification](https://modelcontextprotocol.io/) ## Support For questions or issues: - [Shippo Support Portal](https://support.goshippo.com/) - [API Status](https://status.goshippo.com/) - [Contact Sales](https://goshippo.com/contact/) ## About Shippo Connect with multiple carriers, get discounted shipping labels, track parcels, and much more with just one integration. You can use your own carrier accounts or take advantage of Shippo's discounted rates. Shippo simplifies carrier integrations, rate shopping, tracking, and the entire shipping workflow.