Pirate Ship small business shipping labels MCP server: get rates, buy labels in bulk, import orders.
MCP Server: dev.cotlet/pirate-ship
The MCP server dev.cotlet/pirate-ship provides functionality described as “Labels, rates and tracking for small shippers.” It is focused on shipping-related operations for smaller shipments, based on the server’s stated description.
🛠️ Key Features
Labels
Rates
Tracking
🚀 Use Cases
Generating shipping labels
Retrieving shipping rates
Tracking shipments for small shippers
⚡ Developer Benefits
Clear, shipping-domain scope centered on labels, rates, and tracking
⚠️ Limitations
Available details do not specify supported carrier integrations, protocols, authentication, or tool count.
The Cotlet account this connection acts as: email, workspace, access status, the API key or OAuth client in use with its scope, the apps the workspace may call and its credit balance. Free. Needs the user's Cotlet API key or sign-in.
The apps of the user's workspace and whether each works now: access granted or requested, the app account in the user's Cloud Browser (connected, signed out, not enabled for agents), and the one step the user has to take, with the console link. Free. Needs the user's Cotlet API key or sign-in.
Parameters1
app
string
optional
Only this app, e.g. skool.
Raw schema
{
"type": "object",
"properties": {
"app": {
"type": "string",
"description": "Only this app, e.g. skool."
}
},
"additionalProperties": false
}
cotlet_request_apps
Requests access to apps for the user's workspace, as Request access in the console: a live app is granted at once, any other goes to the Cotlet team, who answer within 72 hours. Takes app slugs as listed at https://cotlet.dev/api/v1/apps. Free. Needs the user's Cotlet API key or sign-in.
Status of an earlier Cotlet call, by its call_id: pending (waits for the owner's approval in the Cotlet console), approved, running, success, rejected, expired, blocked or failed. For a call that answered with status pending or running.
Returns a one-time upload_url and a file_id for a local file (an image for a post, an attachment). The file is sent to upload_url with an HTTP PUT; an argument that takes a file accepts {"file_id": "..."}. Up to 25 MB, the URL works once. Free. Needs the user's Cotlet API key or sign-in.
Sends a report straight to the Cotlet team: a tool that failed or returned wrong data, an error you could not get past, or a tool, field or app the task needed and Cotlet lacks. The report carries the error text and call_id when there is one, never passwords or tokens. Needs the user's Cotlet API key or sign-in.
Parameters7
kind
string
required
bug: a tool did the wrong thing or returned wrong data. error: a call failed or returned an error you could not get past. feature_request: something new the user wants. missing_feature: an app is here but lacks a tool, field or option the task needed. other: anything else.
title
string
required
One line, e.g. 'skool_list_members stops after 50 members'.
description
string
required
What you tried, what you expected and what happened, with the error text if there was one. No passwords, tokens or other secrets.
app
any
optional
App slug the report is about, e.g. 'skool'.
tool
any
optional
Tool or endpoint name, e.g. 'skool_list_members'.
call_id
any
optional
call_id of the call that went wrong, if any.
client
any
optional
Agent or tool sending this, e.g. 'Claude Code'.
Raw schema
{
"type": "object",
"properties": {
"kind": {
"description": "bug: a tool did the wrong thing or returned wrong data. error: a call failed or returned an error you could not get past. feature_request: something new the user wants. missing_feature: an app is here but lacks a tool, field or option the task needed. other: anything else.",
"enum": [
"bug",
"error",
"feature_request",
"missing_feature",
"other"
],
"title": "Kind",
"type": "string"
},
"title": {
"description": "One line, e.g. 'skool_list_members stops after 50 members'.",
"maxLength": 200,
"minLength": 3,
"title": "Title",
"type": "string"
},
"description": {
"description": "What you tried, what you expected and what happened, with the error text if there was one. No passwords, tokens or other secrets.",
"maxLength": 5000,
"minLength": 10,
"title": "Description",
"type": "string"
},
"app": {
"anyOf": [
{
"maxLength": 80,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "App slug the report is about, e.g. 'skool'.",
"title": "App"
},
"tool": {
"anyOf": [
{
"maxLength": 160,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Tool or endpoint name, e.g. 'skool_list_members'.",
"title": "Tool"
},
"call_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "call_id of the call that went wrong, if any.",
"title": "Call Id"
},
"client": {
"anyOf": [
{
"maxLength": 80,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Agent or tool sending this, e.g. 'Claude Code'.",
"title": "Client"
}
},
"required": [
"kind",
"title",
"description"
],
"additionalProperties": false,
"description": "Body of POST /api/v1/reports and the arguments of the MCP tool cotlet_report_issue.",
"title": "AgentReportCreate"
}
cotlet_browser_connect
Wakes the user's Cloud Browser of one app (a real Chrome on Cotlet, signed in to that app as the user) and returns cdp_url, a Chrome DevTools Protocol WebSocket that gives a CDP client full control of the browser. It works in one open tab, the app's: the user watches it live, and new tabs are refused. Every started minute of an open connection costs credits. Needs the user's Cotlet API key or sign-in.
Open Chrome DevTools connections to the user's Cloud Browsers with the minutes and credits each has cost so far, and the cdp_url links still valid. With close: true it ends the open connections and takes back the unused links, of one app or of all. Needs the user's Cotlet API key or sign-in.
Parameters1
close
boolean
optional
End the connections and revoke the links.
Raw schema
{
"type": "object",
"properties": {
"close": {
"type": "boolean",
"description": "End the connections and revoke the links."
}
},
"additionalProperties": false
}
cotlet_browser_open
Wakes the user's own browser on Cotlet, a real Chrome hosted for them: their web browser with the sites they signed in to there, or with `app` that app's browser, signed in to the app. Opens `url` when given and returns the page's URL and title. The user watches every step live. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters1
url
string
optional
A public http or https address, e.g. https://example.com. In an app's browser, a page of that app.
Raw schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "A public http or https address, e.g. https://example.com. In an app's browser, a page of that app."
}
},
"additionalProperties": false
}
cotlet_browser_navigate
Opens a public http or https address in the user's browser on Cotlet and returns the URL and title it ended on. An app's browser opens only that app's pages. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters1
url
string
required
A public http or https address, e.g. https://example.com. In an app's browser, a page of that app.
Raw schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "A public http or https address, e.g. https://example.com. In an app's browser, a page of that app."
}
},
"required": [
"url"
],
"additionalProperties": false
}
cotlet_browser_read
Returns the current page of the user's browser on Cotlet: its readable text, up to 20,000 characters, and a numbered list of its links, buttons and fields. Field values, cookies and storage are never returned. On a page longer than that, both start near where it is scrolled to. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Returns a JPEG image of the visible part of the current page in the user's browser on Cotlet, with its URL and title: boards, canvases and layouts that the page text does not show. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Scrolls the current page in the user's browser on Cotlet with the mouse wheel, as a person does: down or up by `screens` viewport heights (default 0.8), to the top or the bottom, or until element `element` is in view. Content that loads on scroll appears, and the next read lists it. Returns the URL, title and scroll position (at_top, at_bottom). Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters3
direction
string
optional
Where to scroll. Default: down.
screens
number
optional
How far, in viewport heights, for down and up. Default: 0.8.
element
integer
optional
Scroll until this element of the element list is in view.
Raw schema
{
"type": "object",
"properties": {
"direction": {
"type": "string",
"enum": [
"down",
"up",
"top",
"bottom"
],
"description": "Where to scroll. Default: down."
},
"screens": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 10,
"description": "How far, in viewport heights, for down and up. Default: 0.8."
},
"element": {
"type": "integer",
"minimum": 1,
"description": "Scroll until this element of the element list is in view."
}
},
"additionalProperties": false
}
cotlet_browser_click
Clicks a link, button or other element of the current page in the user's browser on Cotlet, by its number in the page's element list, and returns the URL and title after the click. It acts as the user on that site. Buttons that pay or buy and buttons on account or sign-in pages are refused. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters1
element
integer
required
The element's number in the element list of the current page.
Raw schema
{
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "The element's number in the element list of the current page."
}
},
"required": [
"element"
],
"additionalProperties": false
}
cotlet_browser_type
Types text into a field of the current page in the user's browser on Cotlet, by the field's number in the page's element list, and with `submit` presses Enter. Returns the URL and title after it. Password, card and one-time code fields and sign-in pages are refused: the user fills those in themselves. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters3
element
integer
required
The element's number in the element list of the current page.
text
string
required
The text to type.
submit
boolean
optional
Press Enter after typing, e.g. to search.
Raw schema
{
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "The element's number in the element list of the current page."
},
"text": {
"type": "string",
"maxLength": 5000,
"description": "The text to type."
},
"submit": {
"type": "boolean",
"description": "Press Enter after typing, e.g. to search."
}
},
"required": [
"element",
"text"
],
"additionalProperties": false
}
cotlet_browser_select
Chooses an option of a drop-down list on the current page in the user's browser on Cotlet, by the list's number in the element list and the option's label as read lists it (or its value). Returns the URL and title after it. Card fields and account pages are refused. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters2
element
integer
required
The element's number in the element list of the current page.
option
string
required
The option.
Raw schema
{
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "The element's number in the element list of the current page."
},
"option": {
"type": "string",
"maxLength": 300,
"description": "The option."
}
},
"required": [
"element",
"option"
],
"additionalProperties": false
}
cotlet_browser_press
Presses one key on the current page in the user's browser on Cotlet, on the element that has focus: Tab to the next field, Enter to send, Escape to close a dialog or pop-up, arrows to move through a suggestion list. Returns the URL and title after it. Enter on account pages is refused. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Puts files into a file field of the current page in the user's browser on Cotlet, or into the file picker that an upload button opens, by its number in the element list. A file is given as {"url": "https://..."} for a file online or {"file_id": "..."} for one uploaded to Cotlet first; up to 10 files, 20 MB each. Returns the URL and title after it. Every started minute of the session costs credits; it ends when closed or 3 minutes after the last call in that browser.
Parameters2
element
integer
required
The element's number in the element list of the current page.
files
array
required
The files.
Raw schema
{
"type": "object",
"properties": {
"element": {
"type": "integer",
"minimum": 1,
"description": "The element's number in the element list of the current page."
},
"files": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "A public file URL."
},
"file_id": {
"type": "string",
"description": "A file uploaded to Cotlet."
}
},
"additionalProperties": false
},
"description": "The files."
}
},
"required": [
"element",
"files"
],
"additionalProperties": false
}
cotlet_browser_close
Ends the session in the user's browser on Cotlet (with `app`, that app's browser): the browser keeps its cookies, goes to sleep and the per-minute charge stops. Returns the session's minutes and credits.
Buys the labels of a draft batch at the chosen rates; costs real money. Waits for the owner's approval.
Parameters5
batch_id
string
required
A draft from create_shipment, create_batch or create_batch_from_orders.
rate_ids
array
required
One rate_id from get_batch per rate group (a single shipment has one group).
ship_date
string
optional
Default: the batch's ship date.
label_type
string
optional
Printed label or a code the carrier prints at drop-off, when the service offers both.
max_total_usd
number
optional
Refuse when the labels together cost more than this.
Raw schema
{
"type": "object",
"properties": {
"batch_id": {
"type": "string",
"minLength": 1,
"description": "A draft from create_shipment, create_batch or create_batch_from_orders."
},
"rate_ids": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 20,
"minItems": 1,
"description": "One rate_id from get_batch per rate group (a single shipment has one group)."
},
"ship_date": {
"type": "string",
"format": "date",
"description": "Default: the batch's ship date."
},
"label_type": {
"enum": [
"LABEL",
"MOBILE_CODE"
],
"type": "string",
"description": "Printed label or a code the carrier prints at drop-off, when the service offers both."
},
"max_total_usd": {
"type": "number",
"description": "Refuse when the labels together cost more than this.",
"exclusiveMinimum": 0
}
},
"required": [
"batch_id",
"rate_ids"
],
"additionalProperties": false
}
cancel_pickup
Cancels a scheduled USPS or UPS pickup that can still be cancelled. Waits for the owner's approval.
USPS End of Day SCAN Form for the labels of one Ship Date, as a PDF link.
Parameters3
batch_id
string
optional
Only the labels of this batch (ignores ship_date).
ship_date
string
optional
Labels of this Ship Date. Default: today.
from_address_id
string
optional
Ship From Address, when you ship from more than one. Default: the default one.
Raw schema
{
"type": "object",
"properties": {
"batch_id": {
"type": "string",
"description": "Only the labels of this batch (ignores ship_date)."
},
"ship_date": {
"type": "string",
"format": "date",
"description": "Labels of this Ship Date. Default: today."
},
"from_address_id": {
"type": "string",
"description": "Ship From Address, when you ship from more than one. Default: the default one."
}
},
"required": [],
"additionalProperties": false
}
create_ship_from_address
Adds a US Ship From Address, optionally with a separate return address.
Unpaid draft label for one package with every rate; buy it with buy_label.
Parameters13
to
object
required
width_in
number
optional
height_in
number
optional
length_in
number
optional
packaging
string
optional
signature
string
optional
weight_oz
number
optional
Weight in ounces.
ship_from_id
string
optional
Ship-from address id; default: the account's default.
rubber_stamp_1
string
optional
Extra text printed on the label.
rubber_stamp_2
string
optional
insured_value_usd
number
optional
package_preset_id
string
optional
A saved package: its type, size and weight replace the fields above.
address_correction
string
optional
When Pirate Ship suggests a corrected address: ask returns the suggestion without a draft, accept ships to the suggestion, skip keeps the address as given.
Pirate Ship API and MCP server: connect Pirate Ship to ChatGPT and Claude
Yes, ChatGPT, Claude and other AI agents can work in your Pirate Ship account. That includes Cursor, Codex, OpenClaw and any MCP client, plus automations in n8n, Make and Zapier. Ask in plain words, and the AI compares rates, creates USPS and UPS labels, checks tracking and reports what you spent on shipping. It shows you what it will do first and sends nothing to other people until you say so.
As of November 2026, this repo is the missing piece: 51 Pirate Ship tools for AI assistants and scripts.
What you can ask
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?
sign in to Pirate Ship once, about 5 minutes, nothing to install
Python and a terminal
Works in
ChatGPT and Claude apps, on your phone too, Cursor, Codex, OpenClaw, any MCP client, n8n, Make, Zapier, REST API
Claude Code, Claude Desktop, Cursor, Codex on your computer
Runs
24/7, your computer can be off
while your computer is on
Price
7 days free, no card
free
Cotlet is best for online sellers and small shops who want ChatGPT, Claude or another AI agent to work in Pirate Ship for them, with nothing to install.
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/.
Free for your own use, your own business included (license).
Does Pirate Ship have an 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. This repo and Cotlet give you 51 Pirate Ship tools as a REST API and an MCP server.
Can I get a Pirate Ship API key?
Not from Pirate Ship for your own account. With Cotlet you get your own API key that works with your Pirate Ship account, for scripts, n8n, Make, Zapier or any HTTP client. This repo needs no key: it runs on your computer, on your own Pirate Ship session.
Is there an official ChatGPT integration for Pirate Ship?
No. Pirate Ship has no official ChatGPT or Claude connector. Cotlet is an unofficial one that works today, in the ChatGPT and Claude apps and in any AI agent that takes an MCP server.
How do I connect Pirate Ship to ChatGPT?
Sign up at cotlet.dev, sign in to Pirate Ship once in your Cloud Browser there, and add Cotlet to ChatGPT, following the steps in your account. Then ask ChatGPT about your Pirate Ship like you would ask an assistant. ChatGPT needs a server on the internet, so this repo alone, running on your computer, does not connect to ChatGPT.
Can ChatGPT create shipping labels in Pirate Ship?
Yes, with Cotlet. Give it the address and package, and it compares rates, creates the label after your OK and gives you tracking. Labels are paid from your Pirate Ship balance as usual.
Can I automate Pirate Ship with Zapier, Make or n8n?
Pirate Ship has no API and no Zapier app. With Cotlet, n8n, Make and Zapier can compare rates, create labels and check tracking, for example for new orders in a sheet.
Can I use it from my phone?
Yes, with Cotlet: once it is set up, the ChatGPT and Claude apps on your phone can use Pirate Ship for you.
Do I need to be technical?
For Cotlet, no: you sign in to Pirate Ship and add Cotlet to ChatGPT or Claude, with step-by-step instructions in your account. This repo is for people who are fine with Python and a terminal.
Is my Pirate Ship account safe?
Yes. Neither Cotlet nor this repo sees or stores your Pirate Ship password. You sign in yourself, the way you always do, and the AI works on that signed-in session. Anything that reaches other people asks for your OK first: in Cotlet by default, here through your MCP client.
Is it free?
This repo is free, also in your own business. Cotlet is free for 7 days with no card, then one-time credit packs from $29, no subscription. Pricing.
I manage Pirate Ship for several accounts or clients. Does that work?
Yes, with Cotlet. Each Pirate Ship login gets its own connection. Write to contact@cotlet.dev and tell us how many accounts you manage.
How it works
text
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)
You sign in to Pirate Ship in your own Chrome, the way you always do.
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.
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.
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: uv tool upgrade pirate-ship-api-mcp (or pip install -U pirate-ship-api-mcp), from source 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)
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.
Chrome asks whether to allow the connection. Click Allow.
text
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:
--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:
bash
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:
bash
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
bash
claude mcp add pirate-ship -- uvx pirate-ship-api-mcp mcp
# read only:
claude mcp add pirate-ship -- uvx pirate-ship-api-mcp mcp --read-only
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
pirate-ship-mcp serve also serves MCP over streamable HTTP at http://127.0.0.1:8787/mcp, for clients that take a URL:
bash
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
bash
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 -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>:
A CSV of recipients becomes one unpaid draft batch with a Saved Package; prints the rate of each group. Rows without an address are listed, not guessed.
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
Tool
Access
REST route
What it does
get_rates
read
GET /rates
USPS and UPS services with price for one package, cheapest first.
parse_address
read
GET /addresses/parse
Splits a pasted address into name, street, city, state, ZIP and country.
search_recipients
read
GET /recipients/search
Past recipients' addresses matching a name, email or phone.
list_package_types
read
GET /package-types
Packaging types per carrier (box, envelope, flat rate) and the size and weight limits.
Draft labels and batches
Tool
Access
REST route
What it does
create_shipment
write
POST /shipments
Unpaid draft label for one package with every rate; buy it in Pirate Ship.
create_batch
write
POST /batches
Unpaid draft batch for many packages with the rates of each rate group; buy it in Pirate Ship.
create_batch_from_orders
write
POST /batches/from-orders
Turns store orders into a batch of shipments with one saved package; nothing is bought.
get_batch
read
GET /batches/{batch_id}
A draft or bought batch: shipments, tracking, rates to buy, what can be refunded.
list_batches
read
GET /batches
Latest batches and single labels, newest first, with status and tracking counts.
change_ship_date
write
PUT /batches/{batch_id}/ship-date
Moves a draft batch to another ship date and returns its new rates.
rename_batch
write
PATCH /batches/{batch_id}
Change the title of a batch or single label.
delete_batch
write
DELETE /batches/{batch_id}
Deletes an unpaid draft batch or single shipment.
Printing and SCAN Forms
Tool
Access
REST route
What it does
download_labels
read
GET /labels
A download link for the printable labels of a batch or of chosen shipments.
create_scan_form
write
POST /scan-forms
USPS End of Day SCAN Form for the labels of one Ship Date, as a PDF link.
list_scan_forms
read
GET /scan-forms
USPS SCAN Forms per Ship From Address, with their PDF links and labels still without one.
Shipments and tracking
Tool
Access
REST route
What it does
list_shipments
read
GET /shipments
Labels bought in Pirate Ship with recipient, tracking, cost and status, newest first.
get_shipment
read
GET /shipments/{shipment_id}
One shipment with tracking, service, cost, recipient and carrier adjustments.
export_shipments
read
GET /shipments/export
A CSV of the shipments report with every column, as a download link.
Reports, balance and refunds
Tool
Access
REST route
What it does
get_account_balance
read
GET /balance
Account Balance, Pending Refunds and Pending Returns from the Reports page.
get_shipping_stats
read
GET /stats
Labels, spend, savings, tracking and where packages went for a date range, as on Reports.
list_transactions
read
GET /transactions
Every charge, payment and refund on the Pirate Ship balance, newest first.
list_receipts
read
GET /receipts
Payments made to Pirate Ship, newest first; get_receipt shows one.
get_receipt
read
GET /receipts/{receipt_id}
One payment to Pirate Ship with its billing address and the labels it paid for.
list_refunds
read
GET /refunds
Label refunds with their status and amount, newest request first.
list_return_labels
read
GET /return-labels
List the account's pay-on-use return labels and whether each was used.
list_carrier_adjustments
read
GET /carrier-adjustments
Extra charges or credits the carrier made after a label was used, with old and actual package.
export_report
read
GET /reports/{report}/export
A CSV of the transactions, refunds, receipts, return labels or carrier adjustments report.
Pickups
Tool
Access
REST route
What it does
get_pickup_quote
read
GET /pickups/quote
What a USPS or UPS pickup would cost; USPS pickups are free. Nothing is booked.
list_pickups
read
GET /pickups
Your scheduled and past USPS and UPS pickups with confirmation numbers.
Store orders
Tool
Access
REST route
What it does
list_store_connections
read
GET /store-connections
Stores and marketplaces connected to Pirate Ship for order import, with their status.
sync_store_orders
write
POST /import-orders/sync
Pulls new orders from every connected store into Pirate Ship's Import list.
list_import_orders
read
GET /import-orders
Unshipped orders from your connected store integrations, as in the Import grid.
ignore_orders
write
POST /import-orders/ignore
Hides store orders from the Import list without shipping them.
unignore_orders
write
DELETE /import-orders/ignore
Put ignored store orders back on the Import list.
Ship From Addresses
Tool
Access
REST route
What it does
list_ship_from_addresses
read
GET /ship-from-addresses
Your Ship From Addresses with their return addresses; one is the default.
create_ship_from_address
write
POST /ship-from-addresses
Adds a US Ship From Address, optionally with a separate return address.
update_ship_from_address
write
PATCH /ship-from-addresses/{address_id}
Changes a Ship From Address: its name, origin or return address.
set_default_ship_from_address
write
PUT /ship-from-addresses/{address_id}/default
Makes one Ship From Address the default for new shipments and rate quotes.
delete_ship_from_address
write
DELETE /ship-from-addresses/{address_id}
Removes a saved Ship From Address. The default address cannot be removed.
Saved Packages
Tool
Access
REST route
What it does
list_saved_packages
read
GET /saved-packages
Your Saved Packages from Settings: size, weight and the extra services stored with each.
create_saved_package
write
POST /saved-packages
Saves a package (type, size, weight, extra services) for reuse on labels.
update_saved_package
write
PATCH /saved-packages/{package_id}
Changes a Saved Package; fields you leave out keep their values.
delete_saved_package
write
DELETE /saved-packages/{package_id}
Delete a Saved Package (box size and weight preset) from the account.
Tracking emails
Tool
Access
REST route
What it does
get_tracking_email_settings
read
GET /tracking-email-settings
Read whether label recipients get a tracking email, when, and with which template.
update_tracking_email_settings
write
PATCH /tracking-email-settings
Turns default tracking emails on or off and sets their delay after purchase.
list_email_templates
read
GET /email-templates
List the templates of the tracking emails sent to label recipients.
create_email_template
write
POST /email-templates
Adds a tracking email template for the emails recipients get with their tracking link.
update_email_template
write
PATCH /email-templates/{template_id}
Changes a tracking email template; fields you leave out keep their values.
delete_email_template
write
DELETE /email-templates/{template_id}
Delete one tracking email template from the account.
Label settings
Tool
Access
REST route
What it does
get_label_settings
read
GET /label-settings
Read the account's label settings from Settings, General.
update_label_settings
write
PATCH /label-settings
Changes label size, file format, packing list, logo, QR codes, address correction or export format.
Not in this version
Tool
Why
buy_label
Spends your Account Balance or charges your card. Buy in Pirate Ship.
refund_label, refund_batch
Refund requests are final and move money. Request them in Pirate Ship.
schedule_pickup, cancel_pickup
A UPS pickup is charged and its cancellation refunded. get_pickup_quote and list_pickups are here.
dispute_adjustment
A dispute is about a charge on your balance. list_carrier_adjustments is here.
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
Variable
Default
What it does
PIRATE_SHIP_MCP_HOME
~/.config/pirate-ship-api-mcp
Folder of session.json.
PIRATE_SHIP_AUTH_TOKEN
The pirate_id_f0fecf84 cookie, instead of pirate-ship-mcp connect.
PIRATE_SHIP_PROXY
Proxy for every request to Pirate Ship, e.g. http://user:pass@host:port.
PIRATE_SHIP_MCP_READ_ONLY
1 hides and refuses every tool that changes Pirate Ship (same as --read-only).
PIRATE_SHIP_MCP_TOKEN
Bearer token required by serve; needed to listen beyond 127.0.0.1.
PIRATE_SHIP_MCP_HOST, PIRATE_SHIP_MCP_PORT
127.0.0.1, 8787
Address of serve.
TZ
Chrome's zone
Time zone for "today" and date ranges when connect could not read Chrome's.
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.
Status
Code
What to do
401
auth_required, auth_expired
No session, or Pirate Ship signed you out. Sign in to Pirate Ship in Chrome and run pirate-ship-mcp connect.
403
scope_denied
The server runs read-only.
403
target_blocked
Pirate Ship refused the request or showed a bot check. Open ship.pirateship.com in Chrome once, then retry.
409
captcha_required
Pirate Ship asks for a CAPTCHA. Solve it in Chrome.
422
invalid_input
An argument is missing or wrong; the message names it.
429
rate_limited
Pirate Ship is limiting the account. Wait a few minutes.
502
target_error
Pirate Ship answered with an error (an unknown id, an address it cannot rate), or changed its app. git pull for the latest tools, or open an issue.
all 57, with buying, refunds, pickups and disputes
Runs
on your computer, while it is on
in the cloud, 24/7
Pirate Ship session
your Chrome, cookies in a local file
your own Cloud Browser in the EU, profile encrypted with AES-256-GCM, kept signed in
When Pirate Ship changes its app
git pull once we have fixed it
fixed for you, every tool tested daily
Approvals
your MCP client asks per call
purchases and refunds wait for your OK, switchable per tool
Works with
MCP clients on your machine, local scripts
Claude.ai and ChatGPT connectors, n8n, Make, Zapier, any HTTP client
Who may use it
you and your own business
you, teams, businesses, agencies
Price
free
free 7-day trial with 2,000 credits, no card; then one-time packs from $29 for 5,000 credits
On the hosted version a successful call uses 10 credits, failed calls are free, and the Cloud Browser uses 50 credits a day while it has an app enabled for agents. Full pricing.
FAQ
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. 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?
At work and in your own business, yes, free. You may not offer it to others as a hosted or managed service. For client work, use Cotlet or write to contact@cotlet.dev.
Is it open source?
The source is public under the Elastic License 2.0: free to use and change, also in your own business, but not to resell as a hosted service.
A tool broke or I need another one.Open an issue with the tool name and the error message.
Allowed: using it for yourself and in your own business, free. Changing the code and sharing it under the same license.
Not allowed: offering it to others as a hosted or managed service, removing the license notices, getting around its limits.
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.