Pirate Ship by Cotlet

Pirate Ship API とセルフホスト型 MCP サーバー

Python で、Google Chrome のご自身のセッション上で実行する Pirate Ship API と Pirate Ship MCP サーバーです。Cotlet の本番環境で使用している 57 個の Pirate Ship ツールのうち、51 個に対応しています。USPS と UPS の料金、ラベルとバッチの下書き、ラベルのダウンロード、SCAN フォーム、発送と追跡、レポート、ストア注文のインポート、発送元住所、保存済みパッケージ、追跡メール、ラベル設定を利用できます。料金の支払いや返金を行う 6 個のツールはこのバージョンには含まれていません。

Pirate Ship には公開 API も公式 MCP サーバーもありません。このリポジトリでは、その両方を利用できます。

• MCP サーバー：Claude Code、Claude Desktop、Cursor、Codex、その他すべての MCP クライアントに対応し、stdio または HTTP 経由で接続します。セットアップ
• REST API：http://127.0.0.1:8787/api/v1/pirate-ship で利用でき、OpenAPI ドキュメントは /docs にあります。セットアップ
• Python：call("get_rates", to_zip="10001", weight_oz=16) を実行できます。すぐに使えるスクリプトも examples/ に 11 個あります。

このソフトウェアは、ご自身で実行したい技術者向けです。非商用利用に限ります（ライセンス）。サーバー上で 24 時間 365 日稼働させたい場合、Pirate Ship のアプリが変更されても動作する状態を保ちたい場合、チームやビジネスで使いたい場合は、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

目次

• 仕組み
• 要件
• インストール
• Chrome への接続
• MCP サーバー
• REST API
• Python とサンプルスクリプト
• 51 個すべてのツール
• 設定
• セキュリティと Pirate Ship アカウント
• エラー
• セルフホスト版とホステッド版
• よくある質問
• ライセンス

仕組み

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. いつもどおり、ご自身の Chrome で Pirate Ship にサインインします。
2. pirate-ship-mcp connect を実行すると、Chrome DevTools Protocol 経由でその Chrome に接続し、pirateship.com の Cookie と Chrome のタイムゾーンを読み取って、~/.config/pirate-ship-api-mcp/session.json に保存します。このファイルはご自身のユーザーのみが読み取れます。パスワードを読み取ったり保存したりすることはありません。
3. 各ツールの呼び出しでは、Pirate Ship のウェブアプリ自体が ship.pirateship.com/api/graphql に送信する GraphQL オペレーションのいずれかを、Cookie とともに送信します。curl_cffi を使い、Chrome の TLS フィンガープリントを再現します。ヘッドレスブラウザーは実行されません。

Pirate Ship のウェブアプリでは、各オペレーションが永続クエリとして送信されます。永続クエリにはオペレーション名とクエリテキストの sha256 が含まれます。ツールが送信できるのは、operations.py に記載されたオペレーションのみです。アカウント、パスワード、支払い方法、本人確認に関するオペレーションはこの一覧に含まれていません。Pirate Ship が一覧にあるクエリを変更すると、新しいハッシュを記録するまで、ツールは「Pirate Ship changed its app」と応答します。

Pirate Ship のセッション Cookie の有効期間は約 1 日で、使用すると更新されます。Pirate Ship からサインアウトされた場合、Chrome がリモートデバッグを有効にして開いていれば、サーバーは Chrome から Cookie を再度読み取ります。Chrome を開き直した後もサインイン状態が保たれるよう、サインイン時に「サインイン状態を維持する」にチェックを入れてください。

要件

• Python 3.11 以降。
• Pirate Ship にサインイン済みの Google Chrome 144 以降。デバッグポートがあれば、他の Chrome または Chromium も使用できます（オプション B：デバッグポートを開いた Chrome）。
• macOS、Linux、または Windows。
• Ship From Address が設定された Pirate Ship アカウント。料金、下書き、レポート、設定の利用に、それ以外は必要ありません。ラベルを購入するにはアカウント残高または支払い方法が必要です。購入は Pirate Ship 内で行います。

インストール

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

uv を使う場合：uv venv && uv pip install -e . を実行し、その後 uv run pirate-ship-mcp ... を実行します。

AI エージェント（Claude Code、Codex、Cursor）を使ってセットアップしますか？このフォルダーで開き、リポジトリのセットアップを依頼してください。AGENTS.md に手順がすべて記載されており、Chrome での操作が必要な手順だけを尋ねます。

更新するには、git pull && pip install -e . を実行します。ホストされている Pirate Ship ツールの変更は、すべてこのリポジトリに反映されます。

Chrome を接続する

オプション A：普段使っている Chrome（推奨）

1. Chrome で chrome://inspect/#remote-debugging を開き、remote debugging をオンにします。これで Chrome は、このコンピューター上のプログラムからの DevTools 接続を受け付け、接続ごとに確認を求めます。

2. ship.pirateship.com にサインインしていることを確認します。

3. 次を実行します。

   pirate-ship-mcp connect
   

4. Chrome が接続を許可するか確認します。Allow をクリックします。

Saved 32 Pirate Ship cookies to /Users/you/.config/pirate-ship-api-mcp/session.json
Signed in to Pirate Ship as Linda Morales ([email protected])

Pirate Ship からサインアウトした後、サーバーが新しいセッションを自動的に取得できるようにするには、リモートデバッグをオンのままにしてください。Cookie の有効期限は 1 日なので、ほとんどのアプリより頻繁にサインアウトされます。

connect は、Chrome の既定のプロファイルフォルダーにある DevToolsActivePort ファイルを探します。Chrome Beta、Canary、またはカスタムのプロファイルフォルダーを使う場合は、--profile-dir "<folder>" を指定してください。

オプション B：デバッグポートを開いた Chrome

Chrome は既定のプロファイルではデバッグポートを開かないため、別のプロファイルを起動して、そこで一度 Pirate Ship にサインインしてから接続します。

# 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 には ws:// の DevTools URL も指定できます。たとえば、SSH トンネル経由で接続した別のコンピューター上の Chrome の URL を指定できます。

オプション C：Cookie を手動で貼り付ける

Chrome のないサーバーの場合：Chrome で ship.pirateship.com の DevTools を開き、Application > Cookies > https://ship.pirateship.com を選択して、pirate_id_f0fecf84 の値をコピーし、次を実行します。

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

貼り付けた Cookie は自動更新されず、使用しない場合は約 1 日で期限切れになります。Pirate Ship からサインアウトされたら、新しい Cookie を貼り付けてください。

セッションはいつでも次のコマンドで確認できます。

pirate-ship-mcp status

MCP サーバー

MCP サーバーには、各ツールの入力スキーマ、エージェント向けの説明、ヒントが一覧表示されます。読み取りツールには読み取り専用のマークが付けられ、何かを削除するツールや、受取人に届く内容を変更するツールには、クライアントが実行前に確認を求めるようマークが付けられます。

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）または %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 に、Claude Desktop と同じブロックを記述します。設定済みのファイルは 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"]

HTTP 経由

pirate-ship-mcp serve は、URL を指定するクライアント向けに、ストリーミング可能な HTTP 経由でも http://127.0.0.1:8787/mcp で MCP を提供します。

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

次のようなことをエージェントに依頼できます。

2 lb、12x10x6 の箱を ZIP 94103 に送る場合、USPS と UPS ではいくらですか？安い順にしてください。

orders.csv から、保存済みパッケージの「Small box」を使った一括下書きを作成し、グループごとの料金を表示してください。

過去 10 日間のラベルのうち、運送業者によるスキャンがまだないものはどれですか？

10 月にラベルにいくら使いましたか？運送業者による料金調整の内容も教えてください。

REST API

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

各ツールには、/api/v1/pirate-ship 配下に独自のルートがあります。cotlet.dev のホスト型 API と同じパスを使うため、一方を対象に書いたコードはもう一方でも動作します。パスの各部分とクエリー文字列が引数となり、JSON ボディで残りの引数を指定します。

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}'

名前で任意のツールを呼び出し、引数はボディで渡します。

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：すべてのツールについて、ルート、入力スキーマ、回答例を取得します。
• GET /docs：インタラクティブな OpenAPI ドキュメントを表示します。GET /openapi.json では、n8n、Postman、または生成したクライアント向けのスキーマを取得できます。
• 回答は JSON 形式です。レポートのリストは limit と offset を受け取り、total を含めて回答します。

サーバーは 127.0.0.1 のみでリッスンします。別のデバイスからアクセスするにはトークンを設定してください。その場合、すべてのリクエストに Authorization: Bearer <token> が必要です。

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

Python とサンプルスクリプト

サーバーは不要で、Python から直接実行できます。

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)

または、シェルから1つのツールを実行します。pirate-ship-mcp call list_shipments limit=10 のように呼び出すか、JSON オブジェクトを渡します。

examples/ にすぐ使えるスクリプトがあります。各スクリプトは JSON または簡潔なレポートを出力し、必要に応じて --out file.csv または --out file.json を指定できます。また、--help も利用できます。

スクリプト	機能
compare_rates.py	1つの荷物について、USPS と UPS の料金を安い順に表示します。--size 10x8x4、--country を指定できます。
draft_batch_from_csv.py	受取人を記載した CSV から、保存済みパッケージを使った未払いの下書きバッチを1つ作成し、グループごとの料金を表示します。住所のない行は推測せずに一覧表示します。
store_orders.py	接続済みのストアを更新し、発送待ちの注文を一覧表示します。
export_shipments.py	購入済みのラベルを CSV または JSON に出力します。受取人、追跡番号、サービス、料金、ステータスを含みます。--since、--carrier を指定できます。
tracking_report.py	直近 N 日間のラベルのうち、配達済みでないものを、最新イベントと stuck フラグとともに表示します。
refund_candidates.py	重複したラベルと、返金可能期間の28日間に運送業者のスキャンがないラベルを一覧表示します。返金は Pirate Ship で行います。
scan_form.py	今日のラベルの USPS SCAN Form を PDF リンクとして表示します。
pickup_quote.py	運送業者ごとの今日の荷物と重量を、集荷料金とともに表示します。予約は行いません。
carrier_adjustments.py	入力した重量とサイズを運送業者の計測値と並べて、運送業者による調整を表示します。
spend_report.py	指定した期間のラベル、支出、節約額、運送業者別内訳、上位の州、残高を表示します。--transactions を指定すると、すべての請求を保存します。
ship_from_addresses.py	他のツールで使用する ID とともに、発送元住所と保存済みパッケージを表示します。

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"

定期実行する場合、自分のコンピューターが起動していれば cron を使えます。例：0 18 * * 1-5 cd ~/pirate-ship-api-mcp-server && .venv/bin/python examples/tracking_report.py --days 10 --out late.csv。

51個すべてのツール

金額は米ドル、重量はオンス、サイズはインチ、日付は Chrome のタイムゾーンで表示されます。pirate-ship-mcp tools でこの一覧を表示でき、pirate-ship-mcp tools --json では入力スキーマも表示されます。

料金と住所

ツール	アクセス	REST ルート	機能
get_rates	読み取り	GET /rates	1つの荷物について、USPS と UPS のサービスと料金を安い順に表示します。
parse_address	読み取り	GET /addresses/parse	貼り付けた住所を、氏名、番地、市区町村、州、ZIP、国に分割します。
search_recipients	読み取り	GET /recipients/search	氏名、メールアドレス、電話番号に一致する過去の受取人の住所を検索します。
list_package_types	読み取り	GET /package-types	運送業者ごとの梱包タイプ（箱、封筒、定額料金）と、サイズおよび重量の制限を表示します。

下書きラベルとバッチ

ツール	アクセス	REST ルート	機能
create_shipment	書き込み	POST /shipments	1 個の荷物について、すべての料金が表示された未払いの下書きラベルを作成します。Pirate Ship で購入できます。
create_batch	書き込み	POST /batches	複数の荷物について、各料金グループの料金が表示された未払いの下書きバッチを作成します。Pirate Ship で購入できます。
create_batch_from_orders	書き込み	POST /batches/from-orders	ストアの注文を、保存済みの荷物 1 個を使った配送バッチに変換します。購入は行われません。
get_batch	読み取り	GET /batches/{batch_id}	下書きまたは購入済みバッチの情報を取得します。配送、追跡、購入可能な料金、返金可能なものが含まれます。
list_batches	読み取り	GET /batches	最新のバッチと個別ラベルを新しい順に取得します。ステータスと追跡件数も含まれます。
change_ship_date	書き込み	PUT /batches/{batch_id}/ship-date	下書きバッチの発送日を変更し、新しい料金を返します。
rename_batch	書き込み	PATCH /batches/{batch_id}	バッチのタイトルを変更します。
delete_batch	書き込み	DELETE /batches/{batch_id}	未払いの下書きバッチまたは個別の配送を削除します。

印刷と SCAN フォーム

ツール	アクセス	REST ルート	機能
download_labels	読み取り	GET /labels	バッチまたは選択した配送の印刷可能なラベルのダウンロードリンクを取得します。
create_scan_form	書き込み	POST /scan-forms	1 つの発送日のラベル用に、USPS の当日終了時 SCAN フォームを PDF リンクとして作成します。
list_scan_forms	読み取り	GET /scan-forms	発送元住所ごとに USPS SCAN フォームを取得します。PDF リンクと、まだフォームがないラベルも含まれます。

配送と追跡

ツール	アクセス	REST ルート	機能
list_shipments	読み取り	GET /shipments	Pirate Ship で購入したラベルを新しい順に取得します。受取人、追跡情報、費用、ステータスが含まれます。
get_shipment	読み取り	GET /shipments/{shipment_id}	1 件の配送について、追跡情報、サービス、費用、受取人、運送業者による料金調整を取得します。
export_shipments	読み取り	GET /shipments/export	配送レポートの全列を含む CSV をダウンロードリンクとして取得します。

レポート、残高、返金

ツール	アクセス	REST ルート	機能
get_account_balance	読み取り	GET /balance	レポートページに表示されるアカウント残高、保留中の返金、保留中の返品を取得します。
get_shipping_stats	読み取り	GET /stats	レポートと同様に、指定期間のラベル、支出、節約額、追跡情報、荷物の配送先を取得します。
list_transactions	読み取り	GET /transactions	Pirate Ship の残高に関するすべての請求、支払い、返金を新しい順に取得します。
list_receipts	読み取り	GET /receipts	Pirate Ship への支払いを新しい順に取得します。個別の領収書は get_receipt で表示できます。
get_receipt	読み取り	GET /receipts/{receipt_id}	Pirate Ship への 1 件の支払いについて、請求先住所と、その支払いで購入したラベルを取得します。
list_refunds	読み取り	GET /refunds	ラベルの返金を、ステータスと金額とともに、申請日の新しい順に取得します。
list_return_labels	読み取り	GET /return-labels	後払いの返品ラベルと、顧客が使用したかどうかを取得します。
list_carrier_adjustments	読み取り	GET /carrier-adjustments	ラベルの使用後に運送業者が行った追加請求やクレジットを、荷物の元の情報と実際の情報とともに取得します。
export_report	読み取り	GET /reports/{report}/export	取引、返金、領収書、返品ラベル、運送業者による料金調整レポートのいずれかを CSV で取得します。

集荷

ツール	アクセス	REST ルート	機能
get_pickup_quote	読み取り	GET /pickups/quote	USPS または UPS の集荷料金を取得します。USPS の集荷は無料です。予約は行われません。
list_pickups	読み取り	GET /pickups	予約済みおよび過去の USPS と UPS の集荷を、確認番号とともに取得します。

ストア注文

ツール	アクセス	REST ルート	内容
list_store_connections	読み取り	GET /store-connections	注文をインポートするために Pirate Ship に接続されているストアやマーケットプレイスと、そのステータスを一覧表示します。
sync_store_orders	書き込み	POST /import-orders/sync	接続されているすべてのストアから新しい注文を Pirate Ship のインポートリストに取り込みます。
list_import_orders	読み取り	GET /import-orders	接続済みストア連携からの未発送注文を、インポート画面の一覧と同じ形式で表示します。
ignore_orders	書き込み	POST /import-orders/ignore	ストア注文を発送せずにインポートリストから非表示にします。
unignore_orders	書き込み	DELETE /import-orders/ignore	無視したストア注文をインポートリストに戻します。

発送元住所

ツール	アクセス	REST ルート	内容
list_ship_from_addresses	読み取り	GET /ship-from-addresses	返送先住所を含む発送元住所を一覧表示します。1 つがデフォルトです。
create_ship_from_address	書き込み	POST /ship-from-addresses	必要に応じて別の返送先住所を指定して、米国の発送元住所を追加します。
update_ship_from_address	書き込み	PATCH /ship-from-addresses/{address_id}	発送元住所の名前、発送元住所、または返送先住所を変更します。
set_default_ship_from_address	書き込み	PUT /ship-from-addresses/{address_id}/default	1 つの発送元住所を、新しい発送と料金見積もりのデフォルトに設定します。
delete_ship_from_address	書き込み	DELETE /ship-from-addresses/{address_id}	保存済みの発送元住所を削除します。デフォルト住所は削除できません。

保存済みパッケージ

ツール	アクセス	REST ルート	内容
list_saved_packages	読み取り	GET /saved-packages	設定にある保存済みパッケージと、それぞれに保存されたサイズ、重量、追加サービスを一覧表示します。
create_saved_package	書き込み	POST /saved-packages	ラベルで再利用するパッケージ（種類、サイズ、重量、追加サービス）を保存します。
update_saved_package	書き込み	PATCH /saved-packages/{package_id}	保存済みパッケージを変更します。省略したフィールドの値は保持されます。
delete_saved_package	書き込み	DELETE /saved-packages/{package_id}	保存済みパッケージを削除します。そのパッケージで作成したラベルには影響しません。

追跡メール

ツール	アクセス	REST ルート	内容
get_tracking_email_settings	読み取り	GET /tracking-email-settings	受取人にデフォルトで追跡メールを送信するか、購入後どれくらいで送信するか、およびテンプレートを確認します。
update_tracking_email_settings	書き込み	PATCH /tracking-email-settings	デフォルトの追跡メールをオンまたはオフにし、購入後の送信までの時間を設定します。
list_email_templates	読み取り	GET /email-templates	追跡メールのテンプレート（件名、送信者、HTML 本文）を一覧表示します。1 つがデフォルトです。
create_email_template	書き込み	POST /email-templates	受取人に追跡リンクとともに送信する追跡メールのテンプレートを追加します。
update_email_template	書き込み	PATCH /email-templates/{template_id}	追跡メールのテンプレートを変更します。省略したフィールドの値は保持されます。
delete_email_template	書き込み	DELETE /email-templates/{template_id}	追跡メールのテンプレートを削除します。

ラベル設定

ツール	アクセス	REST ルート	内容
get_label_settings	読み取り	GET /label-settings	ラベルのサイズとファイル形式、梱包明細書、ロゴ、QR コード、住所補正、エクスポート形式を確認します。
update_label_settings	書き込み	PATCH /label-settings	ラベルのサイズ、ファイル形式、梱包明細書、ロゴ、QR コード、住所補正、またはエクスポート形式を変更します。

このバージョンには含まれない機能

ツール	理由
buy_label	アカウント残高を使用するか、カードに請求します。Pirate Ship で購入してください。
refund_label, refund_batch	返金リクエストは取り消せず、資金が移動します。Pirate Ship でリクエストしてください。
schedule_pickup, cancel_pickup	UPS の集荷には料金がかかり、キャンセルすると返金されます。get_pickup_quote と list_pickups はここで利用できます。
dispute_adjustment	異議申し立ては残高への請求に関するものです。list_carrier_adjustments はここで利用できます。

ツールの説明にある「buy_label で購入する」とは、Pirate Ship のウェブアプリで下書きを購入することを意味します。意図的に実装していないものは、Pirate Ship へのサインイン、メール、パスワード、セキュリティ設定、支払い方法、請求、および本人確認です。

設定

変数	デフォルト	説明
PIRATE_SHIP_MCP_HOME	~/.config/pirate-ship-api-mcp	session.json の保存フォルダーです。
PIRATE_SHIP_AUTH_TOKEN		pirate-ship-mcp connect の代わりに使用する pirate_id_f0fecf84 Cookie です。
PIRATE_SHIP_PROXY		Pirate Ship へのすべてのリクエストに使用するプロキシです。例：http://user:pass@host:port。
PIRATE_SHIP_MCP_READ_ONLY		1 にすると、Pirate Ship を変更するすべてのツールが非表示になり、使用できなくなります（--read-only と同じです）。
PIRATE_SHIP_MCP_TOKEN		serve で必要なベアラートークンです。127.0.0.1 以外で待ち受ける場合に必要です。
PIRATE_SHIP_MCP_HOST, PIRATE_SHIP_MCP_PORT	127.0.0.1, 8787	serve のアドレスです。
TZ	Chrome のタイムゾーン	connect が Chrome のタイムゾーンを読み取れなかった場合に、「今日」や日付範囲に使用するタイムゾーンです。

セキュリティと Pirate Ship アカウント

• パスワードがこのコードに渡ることはありません。 読み取るのは Cookie のみで、対象は pirateship.com の Cookie に限られます。
• セッションファイルはご自身で管理します。 session.json はモード 0600 で作成されます。このファイルを持つ人は Pirate Ship であなたとして操作できるため、git や共有フォルダーには置かないでください。
• デフォルトではローカルで動作します。 serve は 127.0.0.1 にバインドされ、PIRATE_SHIP_MCP_TOKEN が設定されていない場合、別のアドレスでは起動しません。
• pirateship.com のみが対象です。 pirateship.com 以外へのリクエストやリダイレクトは拒否されます。
• 資金を移動するツールはありません。 ラベルの購入、返金のリクエスト、有料集荷の予約、支払い方法の操作を行うツールはありません。
• 読み取り専用モードです。 --read-only または PIRATE_SHIP_MCP_READ_ONLY=1 を指定すると、29 個の読み取りツールのみが公開されます。
• 変更内容が受取人に届くことがあります。 追跡メールの設定やテンプレートを変更すると、顧客に送信されるメールも変わります。MCP クライアントはそれらのツールの実行前に確認を求めますが、スクリプトは求めません。

エラー

REST API は {"error": "<code>", "message": "..."} を返します。MCP サーバーは同じコードとメッセージをツールエラーとして返します。

ステータス	コード	対処方法
401	auth_required, auth_expired	セッションがないか、Pirate Ship からサインアウトされています。Chrome で Pirate Ship にサインインし、pirate-ship-mcp connect を実行してください。
403	scope_denied	サーバーは読み取り専用で動作しています。
403	target_blocked	Pirate Ship がリクエストを拒否したか、ボットチェックを表示しました。Chrome で ship.pirateship.com を一度開いてから、再試行してください。
409	captcha_required	Pirate Ship が CAPTCHA を要求しています。Chrome で解決してください。
422	invalid_input	引数が不足しているか、正しくありません。メッセージに該当する引数が示されます。
429	rate_limited	Pirate Ship がアカウントへのリクエストを制限しています。数分待ってください。
502	target_error	Pirate Ship がエラーを返しました（不明な ID、料金を計算できない住所など）。またはアプリが変更されました。最新のツールを入手するには git pull を実行するか、issue を作成してください。

セルフホストまたはホステッド

	このリポジトリ	Cotlet、ホステッド
ツール	51	購入、返金、集荷、異議申し立てを含む全57種類
実行場所	電源が入っている間、お使いのコンピューター上	クラウド上、24時間365日
Pirate Ship のセッション	お使いの Chrome。Cookie はローカルファイルに保存	EU 内の専用 Cloud Browser。プロファイルは AES-256-GCM で暗号化され、ログイン状態を維持
Pirate Ship のアプリが変更された場合	修正後に一度 git pull	こちらで修正し、すべてのツールを毎日テスト
承認	MCP クライアントが呼び出しごとに確認	購入と返金は承認を待機。ツールごとに切り替え可能
対応先	お使いのマシン上の MCP クライアント、ローカルスクリプト	Claude.ai と ChatGPT のコネクター、n8n、Make、Zapier、任意の HTTP クライアント
利用者	非商用利用の場合はお客様	チーム、企業、代理店
価格	無料	クレジットカード不要の7日間無料トライアル（2,000クレジット付き）。その後は5,000クレジット29ドルからの買い切りパック

ホステッド版では、成功した呼び出しは20～30クレジット（ほとんどのツールで25クレジット）を使用し、失敗した呼び出しは無料です。また、エージェント向けにアプリを有効にしている間、Cloud Browser は1日あたり50クレジットを使用します。料金の詳細。

よくある質問

Pirate Ship に公式 API はありますか？ ありません。Pirate Ship には API も Webhook も公式 MCP サーバーもありません（2026 年 10 月 11 日確認）。ヘルプセンターにもその旨が記載されており、代わりに組み込みのストア連携とスプレッドシートのアップロードが案内されています。詳細：cotlet.dev/integrations/pirate-ship-api-mcp-server。

Claude、ChatGPT、Cursor 用の Pirate Ship MCP サーバーはありますか？ はい。このサーバーはお使いのマシンで動作します。Claude Code、Claude Desktop、Cursor、Codex では pirate-ship-mcp mcp を実行してください。ChatGPT と Claude.ai のコネクタには公開 HTTPS URL が必要です。ホスト型 Pirate Ship MCP サーバーを利用すると、その URL を取得できます。

スクリプトから USPS と UPS の料金を取得できますか？ はい。get_rates は、Pirate Ship の価格、小売価格、ゾーン、配達予定日を含むすべてのサービスを、料金の安い順に返します。データは保存されません。python examples/compare_rates.py --to-zip 10001 --weight-oz 16 --size 10x8x4 を実行してください。

ラベルを購入できますか？ このリポジトリでは購入できません。各グループの料金を含む下書き（create_shipment、create_batch、create_batch_from_orders）を作成し、Pirate Ship で［購入］をクリックします。ホスト版には、購入ごとの価格上限を設定できる buy_label があります。

スプレッドシートやストアの注文からバッチを作成できますか？ はい。create_batch は 1 回の呼び出しで最大 500 件の宛先を受け取れます。create_batch_from_orders は、連携済みストアから注文を取得します。examples/draft_batch_from_csv.py は CSV を読み込みます。

発送情報と追跡情報を CSV にエクスポートできますか？ はい。python examples/export_shipments.py --since 2026-10-01 --out october.csv を実行するか、export_shipments を使うと、すべての列を含む Pirate Ship 独自のスプレッドシートをエクスポートできます。

なぜ Chrome が必要なのですか？ パスワードを使わずに Pirate Ship のセッションを読み取るためです。Pirate Ship のサインインは Cloudflare のチェックの背後にあるため、ブラウザーでサインインし、その後は通常のリクエストで処理します。Chrome を使うのはサインイン時の 1 回だけで、呼び出しのたびに使うわけではありません。

Pirate Ship からサインアウトされたらどうなりますか？ 呼び出しは auth_expired で失敗します。Chrome のリモートデバッグが有効になっていれば、次の呼び出し時にサーバーが新しい Cookie を読み取ります（Chrome から確認されたら［許可］をクリックしてください）。それ以外の場合は、もう一度 pirate-ship-mcp connect を実行してください。

VPS や Docker で実行できますか？ 技術的には可能で、PIRATE_SHIP_AUTH_TOKEN を使います。使用しないと Cookie は約 1 日で期限切れになり、その後 Pirate Ship はデータセンターの IP アドレスからのセッションと認識します。常時稼働させる場合は、ホスト版を使うと、お客様専用の Cloud Browser にセッションが保持されます。

Pirate Ship のアカウントがブロックされることはありますか？ リクエストには Chrome のフィンガープリントが付与され、ユーザーがクリックするのと同じように、1 件ずつ送信されます。プラットフォームが決して対処しないとは誰にも保証できません。通常の使い方を守ってください。

仕事やクライアント向けに使用できますか？ いいえ。ライセンスで許可されているのは非商用利用のみです。チームや会社での利用、クライアント向けの作業には、Cotlet を利用するか、[email protected] までお問い合わせください。

オープンソースですか？ ソースコードは公開されていますが、ライセンスはオープンソースライセンスではありません。非商用利用のみで、業務での利用は禁止されています。

ツールが動かなくなった場合、または別のツールが必要な場合 ツール名とエラーメッセージを添えて、issue を作成してください。

ライセンス

PolyForm Noncommercial License 1.0.0。概要：

• 許可されること： 非営利目的での利用。ご自身の Pirate Ship アカウントを使った個人的な目的での利用、または慈善団体、学校、公的研究機関、政府機関による利用。コードの変更、および同じライセンスでの共有。
• 許可されないこと： ご自身の事業を含む、あらゆる商用利用。クライアント向けの業務。販売または提供、あるいは本プロジェクトを基にしたサービスの販売または提供。

---

Cotlet（@cotletdev）が保守しています。Pirate Ship は、その所有者の商標です。このプロジェクトは非公式であり、Pirate Ship との提携、同社による推奨または後援を受けていません。