aftership-mcp

A Model Context Protocol server that exposes the AfterShip Tracking and Returns APIs as tools for Claude (and other MCP-compatible clients).

Ask Claude to look up a tracking, create a return, list couriers, audit stuck RMAs, or cross-reference your Shopify orders with their AfterShip trackings — all from natural language.

Tools

Tracking

• list_couriers — list every courier AfterShip can track
• detect_courier — identify the courier for a tracking number
• create_tracking — create a tracking (auto-detects courier if omitted)
• get_tracking — fetch a tracking by AfterShip ID
• list_trackings — list/filter trackings with pagination
• update_tracking — update tracking metadata (title, customer, emails, etc.)
• delete_tracking — delete a tracking

Returns

• list_returns — list/filter return requests
• get_return — fetch a return by ID or RMA number
• create_return — create a return request
• update_return — patch a return

All tools forward to https://api.aftership.com/tracking/2026-01 and https://api.aftership.com/returns/2026-01 with the as-api-key header.

Prerequisites

• Node.js 18+
• An AfterShip account and API key — generate one at admin.aftership.com → Organization → API keys

Install

Option 1 — via npm (recommended once published)

claude mcp add aftership \
  --env AFTERSHIP_API_KEY=your_key_here \
  -- npx -y aftership-mcp

Option 2 — from source

git clone https://github.com/robbiewahl-Vibe-Dev/aftership-mcp.git
cd aftership-mcp
npm install
npm run build

claude mcp add aftership \
  --env AFTERSHIP_API_KEY=your_key_here \
  -- node "$(pwd)/dist/index.js"

Verify with claude mcp list — aftership should show ✓ Connected. Restart Claude Code so the tools register in your next session.

Configuration

| Env var | Required | Description | |---|---|---| | AFTERSHIP_API_KEY | yes | Your AfterShip API key. Treat as a secret. |

Usage examples

Once connected, ask Claude things like:

• "List my couriers."
• "Show me all my AfterShip returns from last quarter."
• "Create a tracking for 1Z999AA10123456784 with title 'Order #1042'."
• "Find returns that were approved more than 30 days ago but never refunded."
• "Cross-reference my last 10 Shopify fulfillments with their AfterShip tracking status." (requires Shopify MCP too)

Development

npm install
npm run dev       # tsc --watch

The server speaks stdio. To debug locally, run AFTERSHIP_API_KEY=… node dist/index.js and pipe MCP requests in.

Architecture notes

• Single-file server in src/index.ts — easy to fork.
• Tool inputs include an extra passthrough on create/update calls so you can send any documented AfterShip body field that isn't first-classed yet, without waiting for an SDK update.
• Errors from AfterShip are surfaced as isError tool results with the original status code and response body, so the LLM can see exactly what went wrong.

Contributing

PRs welcome — especially for additional first-class tool fields, better error messages, or coverage of more AfterShip resources (webhooks, organizations, etc.).

License

MIT © Robbie Wahl