@shippo/shippo-mcp 2.0.18 → 3.0.0

package/README.md

@@ -1,72 +1,56 @@
-# <img src="https://docs.goshippo.com/images/Logo.png" width="30" alt="Shippo logo"> Shippo MCP Server
+# <img src="https://raw.githubusercontent.com/goshippo/ai/main/tools/modelcontextprotocol/assets/shippo-logo.png" width="30" alt="Shippo logo"> Shippo MCP Server
+
+> [!NOTE]
+> This package is a thin **local bridge** to the hosted Shippo MCP server at `https://mcp.shippo.com`. It runs over stdio for MCP clients that connect to a local command, and signs you in with **OAuth** in your browser (no API key required). Tool discovery and execution happen on the hosted server, so the local tool surface always matches hosted. If your client speaks remote MCP with OAuth, you can connect to `https://mcp.shippo.com` directly instead of using this package.
 
 Model Context Protocol (MCP) Server for the Shippo API.
 
-<div align="left">
-    <a href="https://www.speakeasy.com/?utm_source=mcp&utm_campaign=mcp-typescript"><img src="https://custom-icon-badges.demolab.com/badge/-Built%20By%20Speakeasy-212015?style=for-the-badge&logoColor=FBE331&logo=speakeasy&labelColor=545454" /></a>
-</div>
+You must register for a [Shippo account](https://apps.goshippo.com/join) to use our API. It's free to sign up. Only pay to print a live label. Test labels are free.
 
+You sign in through your browser (OAuth), so there is no API key to manage.
 
-You must register for a [Shippo account](https://apps.goshippo.com/join) to use our API. It's free to sign up. Only pay to print a live label — test labels are free.  
-To use the MCP server, you'll need an [API Token](https://docs.goshippo.com/docs/guides_general/authentication/). Replace `YOUR_SHIPPO_API_KEY` with your own token (including the `ShippoToken ` prefix) in the examples below.
+<!-- API-KEY-AUTH (hidden until the hosted key door ships; the code path stays live, this is docs-only):
+For headless or automation use (CI, cron, service accounts) you can supply a Shippo [API token](https://docs.goshippo.com/docs/guides_general/authentication/) instead. A `shippo_test_` key runs in test mode and produces test labels; a `shippo_live_` key runs on your live account, where buying a label is billable.
+-->
 
-<!-- Start Summary [summary] -->
 ## Summary
 
-Shippo MCP Server: Use this MCP Server to integrate with the Shippo service using natural language and agentic flows.
-<!-- End Summary [summary] -->
+Shippo MCP Server: use this MCP server to integrate with the Shippo service using natural language and agentic flows. Compare multi-carrier rates, buy and track labels, validate addresses, and handle customs, all from your MCP client.
 
 ## Requirements
 
-- **Node.js 18+** — [Download Node.js](https://nodejs.org/en/download)
+- **Node.js 18+**: [Download Node.js](https://nodejs.org/en/download)
 
-<!-- Start Table of Contents [toc] -->
 ## Table of Contents
-<!-- $toc-max-depth=2 -->
-* [<img src="https://docs.goshippo.com/images/Logo.png" width="30" alt="Shippo logo"> Shippo MCP Server](#img-srchttpsdocsgoshippocomimageslogopng-width30-altshippo-logo-shippo-mcp-server)
-  * [Requirements](#requirements)
-  * [Quick Start](#quick-start)
-  * [Configuration](#configuration)
-  * [Updating](#updating)
-  * [Troubleshooting](#troubleshooting)
-  * [Features](#features)
-  * [Security](#security)
-  * [Contributions](#contributions)
-  * [Support](#support)
-  * [About Shippo](#about-shippo)
-
-<!-- End Table of Contents [toc] -->
-
-<!-- Start Installation [installation] -->
+
+- [Requirements](#requirements)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Updating](#updating)
+- [Troubleshooting](#troubleshooting)
+- [Features](#features)
+- [Security](#security)
+- [Contributions](#contributions)
+- [Support](#support)
+- [About Shippo](#about-shippo)
+
 ## Quick Start
 
 <details>
 <summary>Cursor</summary>
 
-[![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 (keep the `ShippoToken ` prefix), then save `mcp.json`, and toggle shippo-mcp on and off for changes to take effect.
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=shippo-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzaGlwcG8vc2hpcHBvLW1jcCJdfQ==)
 
-Or manually:
+> Click **Install** to add the server, then start it. The first request opens your browser to sign in to Shippo. No API key needed.
 
-1. Open Cursor Settings
-2. Select Tools and Integrations
-3. Select New MCP Server
-4. If the configuration file is empty paste the following JSON into the MCP Server Configuration:
+Or manually, paste this into your MCP server configuration:
 
 ```json
 {
   "mcpServers": {
     "shippo-mcp": {
       "command": "npx",
-      "args": [
-        "@shippo/shippo-mcp",
-        "start",
-        "--api-key-header",
-        "ShippoToken YOUR_SHIPPO_API_KEY",
-        "--shippo-api-version",
-        "2018-02-08"
-      ]
+      "args": ["-y", "@shippo/shippo-mcp"]
     }
   }
 }
@@ -77,8 +61,22 @@ Or manually:
 <details>
 <summary>Claude Code CLI</summary>
 
+Add the Shippo MCP server to Claude Code (opens your browser to sign in on first use):
+
+```bash
+claude mcp add --transport stdio shippo-mcp -- npx -y @shippo/shippo-mcp
+```
+
+Verify it was added:
+
+```bash
+claude mcp list
+```
+
+To remove if needed:
+
 ```bash
-claude mcp add @shippo/shippo-mcp npx @shippo-mcp start -- --api-key-header "ShippoToken YOUR_SHIPPO_API_KEY" --shippo-api-version 2018-02-08
+claude mcp remove shippo-mcp
 ```
 
 </details>
@@ -86,27 +84,20 @@ claude mcp add @shippo/shippo-mcp npx @shippo-mcp start -- --api-key-header "Shi
 <details>
 <summary>Claude Desktop</summary>
 
-You need to do the following
-1. Open claude Desktop
-2. Open left hand side pane, then click on your Username
-3. Go to `Settings`
-4. Go to `Developer` tab (on the left hand side)
-5. Click on `Edit Config`
-Paste the following config in the configuration
+**Desktop Extension (recommended):**
+
+[![Add to Claude Desktop](https://img.shields.io/badge/Add_to_Claude_Desktop-Download_.dxt-d97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/goshippo/ai/releases/download/shippo-mcp-v3.0.0/shippo.dxt)
+
+Click to download `shippo.dxt`, then open it in Claude Desktop to install (or Settings -> Extensions -> Advanced -> Install Extension). It signs in with OAuth on first use, so there is nothing to configure. You can also build it yourself with `npm run build-dxt`.
+
+**Manual config:** Settings -> Developer -> Edit Config, then paste:
 
 ```json
 {
   "mcpServers": {
     "shippo-mcp": {
       "command": "npx",
-      "args": [
-        "@shippo/shippo-mcp",
-        "start",
-        "--api-key-header",
-        "ShippoToken YOUR_SHIPPO_API_KEY",
-        "--shippo-api-version",
-        "2018-02-08"
-      ]
+      "args": ["-y", "@shippo/shippo-mcp"]
     }
   }
 }
@@ -114,96 +105,85 @@ Paste the following config in the configuration
 
 </details>
 
-
 <details>
-<summary> Manual CLI usage </summary>
+<summary>Manual CLI usage</summary>
 
-If you need to start the MCP server manually (e.g., for use with other MCP clients or debugging), run:
+To start the server manually (for other MCP clients or debugging):
 
 ```bash
-npx @shippo/shippo-mcp start --api-key-header "ShippoToken YOUR_SHIPPO_API_KEY" --shippo-api-version 2018-02-08
+npx -y @shippo/shippo-mcp
 ```
 
-> **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.
+> **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. On the first request it opens your browser to sign in.
 
-For a full list of server arguments, run:
+For the full list of flags:
 
 ```bash
 npx @shippo/shippo-mcp --help
 ```
 
 </details>
-<!-- End Installation [installation] -->
-
-<!-- Start Configuration [configuration] -->
 
 ## Configuration
 
-### Cursor / Claude
+### Authentication
+
+No configuration needed. On the first request the bridge opens your browser to sign in to Shippo, then caches the session locally (see [Security](#security)).
 
 ```json
 {
   "mcpServers": {
     "shippo-mcp": {
       "command": "npx",
-      "args": [
-        "@shippo/shippo-mcp",
-        "start",
-        "--api-key-header",
-        "ShippoToken YOUR_SHIPPO_API_KEY",
-        "--shippo-api-version",
-        "2018-02-08"
-      ]
+      "args": ["-y", "@shippo/shippo-mcp"]
     }
   }
 }
 ```
 
-### Command Line
+<!-- API-KEY-AUTH (hidden until the hosted key door ships; the code path stays live, this is docs-only):
+
+### API key (headless / CI / automation)
+
+Prefer the `SHIPPO_API_KEY` environment variable so the key is not visible in the process list or persisted into client config:
 
 ```bash
-npx @shippo/shippo-mcp start --api-key-header "ShippoToken YOUR_SHIPPO_API_KEY" --shippo-api-version 2018-02-08
+SHIPPO_API_KEY=<your-shippo-key> npx -y @shippo/shippo-mcp
 ```
 
-<details>
-<summary>Development</summary>
+The `--api-key=shippo_test_xxxxx` flag also works, but the key is then visible to other local users in the process list, so reserve it for throwaway test keys.
 
-To build the server from source:
+-->
 
-1. Clone the repository
-2. Install dependencies: `npm install`
-3. Build the server: `npm run build`
-4. The server binary will be at `bin/mcp-server.js`
+### Flags
 
-#### Local Configuration
+<!-- API-KEY-AUTH: restore this row to the table when the key door ships:
+| `SHIPPO_API_KEY` (env, preferred) or `--api-key=<key>` | Use a Shippo API key instead of OAuth. |
+-->
 
-To run the server locally from source (e.g., for development), use the following configuration in Cursor or Claude:
+| Flag | Purpose |
+|------|---------|
+| `--url=<url>` | Override the server (default `https://mcp.shippo.com`). Must be `https`, except `localhost` for local testing, since credentials are sent to it. |
+| `--shippo-account=<id>` | Act on a managed account (sends `SHIPPO-ACCOUNT-ID`). |
+| `--callback-port=<n>` | Pin the OAuth loopback callback port (integer 1024-65535). By default it is derived deterministically per host, so re-authorization keeps matching the registered redirect. |
+| `--help` | Print usage and exit. |
+| `--version` | Print the version and exit. |
 
-```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"
-      ]
-    }
-  }
-}
-```
+### Claude Code CLI
 
-Replace `/ABSOLUTE/PATH/TO/REPO` with the full path to your cloned repository.
+```bash
+# Add the MCP server (OAuth)
+claude mcp add --transport stdio shippo-mcp -- npx -y @shippo/shippo-mcp
 
-</details>
+# List configured servers
+claude mcp list
 
-<!-- End Configuration [configuration] -->
+# Get details about the server
+claude mcp get shippo-mcp
 
-<!-- Start Updating [updating] -->
+# Remove the server
+claude mcp remove shippo-mcp
+```
 
 ## Updating
 
@@ -225,8 +205,6 @@ Next time you start your MCP client (Cursor, Claude), it will fetch the latest v
 
 > **Tip:** After updating, toggle your MCP server off and on in Cursor/Claude settings for changes to take effect.
 
-<!-- End Updating [updating] -->
-
 ## Troubleshooting
 
 ### `ReferenceError: Response is not defined`
@@ -259,34 +237,17 @@ which npx   # Should point to v20 or v18 path
 
 Then restart your MCP client (Cursor/Claude Desktop).
 
-**Alternative: Global Install**
+<!-- API-KEY-AUTH (hidden until the hosted key door ships; the workaround is API-key auth):
 
-If cache issues persist, install globally instead of using npx:
+### Sign-in does not open a browser (headless / SSH)
 
-```bash
-npm install -g @shippo/shippo-mcp
-```
+OAuth needs a local browser and a loopback callback on the same machine. In CI, containers, or an SSH session with no display, sign-in cannot complete. Use an API key instead: `SHIPPO_API_KEY=<your-shippo-key>`.
 
-Then update your MCP configuration to use the global command directly:
+-->
 
-```json
-{
-  "mcpServers": {
-    "shippo-mcp": {
-      "command": "shippo-mcp",
-      "args": [
-        "start",
-        "--api-key-header",
-        "ShippoToken YOUR_SHIPPO_API_KEY",
-        "--shippo-api-version",
-        "2018-02-08"
-      ]
-    }
-  }
-}
-```
+### Reset sign-in
 
-<!-- Start Features [features] -->
+OAuth session state (registered client, tokens, PKCE verifier) is cached under `~/.shippo-mcp`, in a per-host subdirectory. Delete that directory to fully reset and start a fresh sign-in on the next run.
 
 ## Features
 
@@ -337,25 +298,30 @@ Then update your MCP configuration to use the global command directly:
 - Create and manage batch shipments
 - Bulk label generation
 - Batch processing for high-volume shipping
-  <!-- End Features [features] -->
-
-<!-- Start Security [security] -->
 
 ## Security
 
+### Authentication
+
+- **OAuth**: sign in through your browser. No API key is stored; the session is cached locally under `~/.shippo-mcp` and can be reset by deleting that directory.
+
+<!-- API-KEY-AUTH (hidden until the hosted key door ships; the code path stays live, this is docs-only):
+
+- **API key (optional)**: for headless and automation use. Prefer the `SHIPPO_API_KEY` environment variable over the `--api-key` flag so the key stays out of the process list.
+
 ### API Key Management
 
-- **Test Keys**: Use test API keys for development and testing
-- **Live Keys**: Use live API keys only in production environments
-- **Never commit** API keys to source control
-- **Environment Variables** recommended for sensitive data
+- **Test Keys**: use test API keys (`shippo_test_...`) for development and testing.
+- **Live Keys**: use live API keys (`shippo_live_...`) only in production environments.
+- **Never commit** API keys to source control.
+- **Environment variables** are recommended for sensitive data.
 
 ### Getting Your API Key
 
 1. Sign up at [goshippo.com](https://goshippo.com)
 2. Go to [API Keys](https://apps.goshippo.com/api)
 3. Generate a key
-4. Use it in your MCP configuration
+4. Use it via `SHIPPO_API_KEY`
 
 ### Best Practices
 
@@ -363,7 +329,8 @@ Then update your MCP configuration to use the global command directly:
 - Rotate keys regularly
 - Never share keys publicly
 - Store sensitive configuration in environment variables
-  <!-- End Security [security] -->
+
+-->
 
 ## Contributions
 
@@ -373,7 +340,6 @@ We welcome contributions! Please:
 - Submit pull requests for improvements
 - Share feedback and suggestions
 
-
 ## Support
 
 For support and questions:
@@ -383,5 +349,4 @@ For support and questions:
 
 ## About Shippo
 
-Connect with multiple different 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.
-<!-- Placeholder for Future Speakeasy SDK Sections -->
+Connect with multiple different 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.