Pirate Ship API and MCP server, self-hosted

A Pirate Ship API and a Pirate Ship MCP server you run on your own computer, in Python, on the session of your own Google Chrome. 51 of the 57 Pirate Ship tools we run in production at Cotlet: USPS and UPS rates, draft labels and batches, label downloads, SCAN Forms, shipments and tracking, reports, store order import, Ship From Addresses, Saved Packages, tracking emails and label settings. The six tools that spend or refund money are not in this version.

Pirate Ship has no public API and no official MCP server. This repo gives you both:

• MCP server for Claude Code, Claude Desktop, Cursor, Codex and any MCP client, over stdio or HTTP. Setup

• REST API on http://127.0.0.1:8787/api/v1/pirate-ship, with OpenAPI docs at /docs. Setup

• Python: call("get_rates", to_zip="10001", weight_oz=16), plus 11 ready scripts in examples/.

It is for technical people who want to run it themselves, for personal use only (license). If you want it running 24/7 on a server, kept working when Pirate Ship changes its app, for a team or a business, use the hosted version at cotlet.dev.

git clone https://github.com/cotletdev/pirate-ship-api-mcp-server.git && cd pirate-ship-api-mcp-server
python3 -m venv .venv && . .venv/bin/activate && pip install -e .
pirate-ship-mcp connect                            # reads your Pirate Ship session from Chrome
pirate-ship-mcp call get_rates to_zip=10001 weight_oz=16
claude mcp add pirate-ship -- "$PWD/.venv/bin/pirate-ship-mcp" mcp

Contents

• How it works

• Requirements

• Install

• Connect your Chrome

• MCP server

• REST API

• Python and the example scripts

• All 51 tools

• Configuration

• Security and your Pirate Ship account

• Errors

• Self-hosted or hosted

• FAQ

• License

Related MCP server: AKIMCP

How it works

AI agent (MCP) / script (REST, Python) ──▶ pirate-ship-mcp on your computer ──your cookies──▶ ship.pirateship.com
                                                     ▲
                       pirate-ship-mcp connect ──────┘ reads them once from your Chrome (DevTools Protocol)

1. You sign in to Pirate Ship in your own Chrome, the way you always do.

2. pirate-ship-mcp connect attaches to that Chrome through the Chrome DevTools Protocol, reads the pirateship.com cookies and Chrome's time zone, and saves them to ~/.config/pirate-ship-api-mcp/session.json, readable by your user only. It never sees or stores your password.

3. Every tool call is one of the GraphQL operations Pirate Ship's own web app sends to ship.pirateship.com/api/graphql, with those cookies, sent with curl_cffi, which copies Chrome's TLS fingerprint. No headless browser runs.

Pirate Ship's web app sends each operation as a persisted query: its name and the sha256 of the query text. The tools may send only the operations listed in operations.py, and account, password, payment method and identity operations are not on that list. When Pirate Ship changes one of the listed queries, the tool answers "Pirate Ship changed its app" until we record the new hash.

Pirate Ship's session cookie lives about a day and is renewed by use. When Pirate Ship signs you out, the server reads the cookies from Chrome again, if Chrome is open with remote debugging on. Tick "Stay signed in" when you sign in, so Chrome keeps you signed in between visits.

Requirements

• Python 3.11 or newer.

• Google Chrome 144 or newer, signed in to Pirate Ship. Any Chrome or Chromium works with a debugging port.

• macOS, Linux or Windows.

• A Pirate Ship account with a Ship From Address. Rates, drafts, reports and settings need nothing else. Buying labels needs Account Balance or a payment method, and you buy in Pirate Ship itself.

Install

git clone https://github.com/cotletdev/pirate-ship-api-mcp-server.git
cd pirate-ship-api-mcp-server
python3 -m venv .venv
. .venv/bin/activate              # Windows: .venv\Scripts\activate
pip install -e .
pirate-ship-mcp --version

With uv: uv venv && uv pip install -e ., then uv run pirate-ship-mcp ....

Setting it up with an AI agent (Claude Code, Codex, Cursor)? Open it in this folder and ask it to set up the repo: AGENTS.md tells it every step, and it asks you only for the steps in Chrome.

To update: git pull && pip install -e .. We copy every change of the hosted Pirate Ship tools into this repo.

Connect your Chrome

Option A: your everyday Chrome (recommended)

1. Open chrome://inspect/#remote-debugging in Chrome and switch remote debugging on. Chrome then accepts DevTools connections from programs on this computer, and asks you before each one.

2. Make sure you are signed in at ship.pirateship.com.

3. Run:

   pirate-ship-mcp connect

4. Chrome asks whether to allow the connection. Click Allow.

Saved 32 Pirate Ship cookies to /Users/you/.config/pirate-ship-api-mcp/session.json
Signed in to Pirate Ship as Linda Morales (linda@example.com)

Leave remote debugging on if you want the server to pick up a new session by itself after Pirate Ship signs you out. With a one-day cookie, that happens more often than with most apps.

connect looks for Chrome's DevToolsActivePort file in the default profile folder. For Chrome Beta, Canary or a custom profile folder, pass --profile-dir "<folder>".

Option B: a Chrome with a debugging port

Chrome does not open a debugging port on your default profile, so start a separate one, sign in to Pirate Ship there once, and connect to it:

# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-pirate-ship"
# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-pirate-ship"
# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="%USERPROFILE%\.chrome-pirate-ship"

pirate-ship-mcp connect --cdp http://127.0.0.1:9222

--cdp also takes a ws:// DevTools URL, for example of a Chrome on another machine reached over an SSH tunnel.

Option C: paste the cookie by hand

For a server with no Chrome: in Chrome open DevTools on ship.pirateship.com, Application > Cookies > https://ship.pirateship.com, copy the value of pirate_id_f0fecf84, then:

pirate-ship-mcp connect --token          # paste it, input is hidden
# or, without a session file:
export PIRATE_SHIP_AUTH_TOKEN=...

A pasted cookie is not refreshed on its own, and this one lasts about a day without use. Paste a new one when Pirate Ship signs you out.

Check the session at any time:

pirate-ship-mcp status

MCP server

The MCP server lists every tool with its input schema, a description written for agents, and hints: read tools are marked read-only, and tools that delete something or change what your recipients get are marked so your client asks before running them.

Claude Code

claude mcp add pirate-ship -- /path/to/pirate-ship-api-mcp-server/.venv/bin/pirate-ship-mcp mcp
# read only:
claude mcp add pirate-ship -- /path/to/pirate-ship-api-mcp-server/.venv/bin/pirate-ship-mcp mcp --read-only

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "pirate-ship": {
      "command": "/path/to/pirate-ship-api-mcp-server/.venv/bin/pirate-ship-mcp",
      "args": ["mcp"]
    }
  }
}

Cursor

~/.cursor/mcp.json, the same block as Claude Desktop. A ready copy is in mcp.json.

Codex

~/.codex/config.toml:

[mcp_servers.pirate-ship]
command = "/path/to/pirate-ship-api-mcp-server/.venv/bin/pirate-ship-mcp"
args = ["mcp"]

Over HTTP

pirate-ship-mcp serve also serves MCP over streamable HTTP at http://127.0.0.1:8787/mcp, for clients that take a URL:

pirate-ship-mcp serve
claude mcp add --transport http pirate-ship http://127.0.0.1:8787/mcp

Then ask your agent things like:

What does a 2 lb box, 12x10x6, cost to ZIP 94103 with USPS and UPS? Cheapest first.

Make a draft batch from orders.csv with my "Small box" Saved Package and show me the rates per group.

Which labels from the last 10 days still have no carrier scan?

How much did I spend on labels in October, and what were the carrier adjustments?

REST API

pirate-ship-mcp serve              # http://127.0.0.1:8787, MCP at /mcp, docs at /docs

Each tool has its own route under /api/v1/pirate-ship, the same paths as the hosted API at cotlet.dev, so code written against one works with the other. Path parts and the query string are arguments, and a JSON body adds the rest.

curl 'http://127.0.0.1:8787/api/v1/pirate-ship/balance'
curl 'http://127.0.0.1:8787/api/v1/pirate-ship/rates?to_zip=10001&weight_oz=16&length_in=10&width_in=8&height_in=4'
curl 'http://127.0.0.1:8787/api/v1/pirate-ship/shipments?from_date=2026-10-01&limit=50'
curl -X POST http://127.0.0.1:8787/api/v1/pirate-ship/shipments \
  -H 'Content-Type: application/json' \
  -d '{"full_name": "Linda Morales", "address1": "350 5th Ave", "city": "New York", "state": "NY", "zip": "10118", "weight_oz": 20}'

Any tool by name, body as its arguments:

curl -X POST http://127.0.0.1:8787/api/v1/pirate-ship/tools/list_shipments -d '{"carrier": ["UPS"]}'

• GET /api/v1/pirate-ship/tools: every tool with its route, input schema and an example answer.

• GET /docs: interactive OpenAPI docs, GET /openapi.json the schema, for n8n, Postman or a generated client.

• Answers are JSON. Report lists take limit and offset and answer with total.

The server listens on 127.0.0.1 only. To reach it from another device of yours, set a token, and every request then needs Authorization: Bearer <token>:

PIRATE_SHIP_MCP_TOKEN=$(openssl rand -hex 24) pirate-ship-mcp serve --host 0.0.0.0

Python and the example scripts

Straight from Python, no server needed:

from pirate_ship_api_mcp import call
from pirate_ship_api_mcp.scripting import paginate_offset, write_rows

rates = call("get_rates", to_zip="10001", weight_oz=16, length_in=10, width_in=8, height_in=4)["rates"]
shipments = list(paginate_offset("list_shipments", {"from_date": "2026-10-01"}, "shipments"))
write_rows(shipments, "october.csv")
call("create_shipment", full_name="Linda Morales", address1="350 5th Ave", city="New York", zip="10118", weight_oz=20)

Or one tool from the shell: pirate-ship-mcp call list_shipments limit=10, or with a JSON object.

Ready scripts in examples/. Each prints JSON or a short report, takes --out file.csv or --out file.json where it makes sense, and --help:

python examples/compare_rates.py --to-zip 94103 --weight-oz 32 --size 12x10x6
python examples/draft_batch_from_csv.py orders.csv --title "Wholesale 19 Oct" --package "Small box"

On a schedule, cron on your own computer works while it is on: 0 18 * * 1-5 cd ~/pirate-ship-api-mcp-server && .venv/bin/python examples/tracking_report.py --days 10 --out late.csv.

All 51 tools

Money is in US dollars, weights in ounces, sizes in inches, dates in Chrome's time zone. pirate-ship-mcp tools prints this list, pirate-ship-mcp tools --json adds the input schemas.

Rates and addresses

Draft labels and batches

Printing and SCAN Forms

Shipments and tracking

Reports, balance and refunds

Pickups

Store orders

Ship From Addresses

Saved Packages

Tracking emails

Label settings

Not in this version

In tool descriptions "buy it with buy_label" means: buy the draft in Pirate Ship's web app. Never built, on purpose: your Pirate Ship sign-in, email, password, security settings, payment methods, billing and identity checks.

Configuration

Security and your Pirate Ship account

• Your password never reaches this code. Only cookies are read, and only those of pirateship.com.

• The session file is yours. session.json is created with mode 0600. Anyone who has it can act as you on Pirate Ship, so keep it out of git and shared folders.

• Local by default. serve binds to 127.0.0.1 and refuses another address without PIRATE_SHIP_MCP_TOKEN.

• pirateship.com only. Requests and redirects outside pirateship.com are refused.

• No tool moves money. None buys a label, requests a refund, books a paid pickup or touches your payment methods.

• Read-only mode. --read-only or PIRATE_SHIP_MCP_READ_ONLY=1 exposes the 29 read tools only.

• Some changes reach your recipients. Tracking email settings and templates change the emails your customers get. MCP clients ask before those tools run; a script does not.

Errors

The REST API answers {"error": "<code>", "message": "..."}. The MCP server returns the same code and message as a tool error.

Self-hosted or hosted

On the hosted version a successful call uses 20 to 30 credits (25 for most tools), failed calls are free, and the Cloud Browser uses 50 credits a day while it has an app enabled for agents. Full pricing.

FAQ

Does Pirate Ship have an official API? No. Pirate Ship has no API, no webhooks and no official MCP server (checked 11 Oct 2026). Its help center says so and points to the built-in store integrations and spreadsheet uploads instead. Details: cotlet.dev/integrations/pirate-ship-api-mcp-server.

Is there a Pirate Ship MCP server for Claude, ChatGPT or Cursor? Yes, this one runs on your machine: pirate-ship-mcp mcp for Claude Code, Claude Desktop, Cursor and Codex. ChatGPT and Claude.ai connectors need a public HTTPS URL, which the hosted Pirate Ship MCP server gives you.

Can I get USPS and UPS rates from a script? Yes. get_rates returns every service with Pirate Ship's price, the retail price, zone and delivery estimate, cheapest first, and saves nothing: python examples/compare_rates.py --to-zip 10001 --weight-oz 16 --size 10x8x4.

Can it buy labels? Not this repo. It builds the draft (create_shipment, create_batch, create_batch_from_orders) with the rates of each group, and you click Buy in Pirate Ship. The hosted version has buy_label with a price cap per purchase.

Can I create a batch from a spreadsheet or from my store orders? Yes. create_batch takes up to 500 recipients per call, create_batch_from_orders takes orders from your connected stores. examples/draft_batch_from_csv.py reads a CSV.

Can I export shipments and tracking to CSV? Yes: python examples/export_shipments.py --since 2026-10-01 --out october.csv, or export_shipments for Pirate Ship's own spreadsheet with every column.

Why does it need my Chrome? To read your Pirate Ship session without your password. Pirate Ship's sign-in sits behind a Cloudflare check, so you sign in in the browser and plain requests do the rest. Chrome is used once per sign-in, not for each call.

What happens when Pirate Ship signs me out? Calls fail with auth_expired. With Chrome remote debugging on, the server reads the new cookies on the next call (click Allow when Chrome asks); otherwise run pirate-ship-mcp connect again.

Can it run on a VPS or in Docker? Technically yes, with PIRATE_SHIP_AUTH_TOKEN. The cookie lasts about a day without use, Pirate Ship then sees your session from a datacenter IP, and the license allows it only on a server you alone use. For an always-on setup the hosted version keeps your session in your own Cloud Browser.

Will my Pirate Ship account get blocked? Requests carry Chrome's fingerprint and go out one at a time, as you would click. Nobody can promise a platform never acts. Keep to your normal use.

Can I use it at work or for my clients? No, the license is for personal use by one person. For a team, a company or client work, use Cotlet or write to contact@cotlet.dev.

Is it open source? The source is public, the license is not an open source license: personal use only, no business use, no hosting for others.

A tool broke or I need another one. Open an issue with the tool name and the error message.

License

Cotlet Personal Use License 1.0. In short:

• Allowed: one person, on their own computers, with their own Pirate Ship accounts, for their own purposes. Changing the code for yourself, and a GitHub fork under the same license.

• Not allowed: any use in or for a company or organization, your own business included; letting other people use your instance (shared server, team machine, cloud service); selling or offering it or a service built on it.

Maintained by Cotlet (@cotletdev). Pirate Ship is a trademark of its owner. This project is unofficial and not affiliated with, endorsed or sponsored by Pirate Ship.