🤖MCP server

mcp-shippified is a Model Context Protocol server that exposes the Shippified API as tools. Once it's connected, Claude Desktop, Claude Code or any other MCP client can list and create orders, check tracking, manage bots and email sources, and set up webhooks in your workspace.

It's a thin layer over the TypeScript SDK: each tool call becomes one REST request authenticated with your API key. It talks over stdio, so the MCP client starts it as a local program. The current version is 0.2.0.

Before you start

• Node 18 or newer.

• A Shippified API key made for this purpose. Create it under Settings → Developer (see Authentication) and name it after the client, such as Claude Desktop, so you can revoke it on its own.

Install

The build bundles the SDK source from the neighbouring shippified-sdk folder into one executable file, dist/index.js, so you don't build the SDK separately. The MCP protocol library (@modelcontextprotocol/sdk) is a normal dependency that npm install fetches.

cd mcp-shippified
npm install
npm run build            # type-checks, then bundles to dist/index.js
./dist/index.js --help

cd mcp-shippified
npm install
npm pack                                        # builds, then writes mcp-shippified-0.2.0.tgz
npm install -g ./mcp-shippified-0.2.0.tgz       # puts `mcp-shippified` on your PATH
mcp-shippified --version

dist/index.js is executable and accepts two flags: --help / -h (usage and environment variables) and --version / -v (prints 0.2.0). With no flags it waits for JSON-RPC on stdin; run by hand it looks like it hangs, which is expected.

Configure

In the examples, replace /absolute/path/to/mcp-shippified with where the folder is. After a global tarball install, use the command mcp-shippified with no arguments instead.

claude mcp add shippified \
  -e SHIPPIFIED_TOKEN="$SHIPPIFIED_API_KEY" \
  -- node /absolute/path/to/mcp-shippified/dist/index.js

{
  "mcpServers": {
    "shippified": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-shippified/dist/index.js"],
      "env": {
        "SHIPPIFIED_TOKEN": "sk_your_key_here",
        "SHIPPIFIED_BASE_URL": "https://shippified.net"
      }
    }
  }
}

To debug outside a client, run the official MCP Inspector:

SHIPPIFIED_TOKEN="$SHIPPIFIED_API_KEY" \
  npx @modelcontextprotocol/inspector \
  node /absolute/path/to/mcp-shippified/dist/index.js

For development, npm run dev runs the server straight from TypeScript without building.

Tools

The server exposes 49 tools. Each returns the API's JSON response as formatted text.

Public and status (4)

Workspace and orders (10)

Bots (5)

Email (5)

Templates (3)

Recurring costs (4)

Share cards (3)

Billing and account settings (4)

API keys (3)

Outbound webhooks (6)

Intake log (2)

How the tools behave

The tool descriptions give the assistant these rules, so it can explain them to you:

• Status can't be set. It comes from parsing and carrier tracking. list_orders offers only the real status values, so a status filter always filters.

• update_order is fill-missing-only. salePriceCents can always change (null clears it). Every other field is written only if empty, and itemSummary only while the order is "Unparsed order". Adding a tracking number to an ordered order moves it to shipped.

• reparse_orders re-runs parsing on stored messages with the current shapes and your templates, keeping hand-entered values and carrier data, and returns { reparsed, changed, merged, removed, skipped }. Use it after changing a template.

• rebuild_email_source is destructive. It re-reads the mailbox and replaces the orders that source produced in the window. It refuses up front, changing nothing, for forwarding sources and for sources that need reconnecting or are paused. It returns immediately; check rebuilding and lastRebuild with get_email_source. Edited orders and ones that also came from Discord or manual entry are kept.

• detect_template is read-only. It shows which template would win, whether an email would be ignored, and the order it would produce. Pass draft to test an unsaved template.

• import_email creates real orders, through the same pipeline as live mail (allowed senders, Message-ID dedup, plan limit).

• sync_tracking refreshes up to 50 in-flight orders on carriers with live tracking and uses carrier quota. A background tracker already does this, so it's rarely needed.

• create_webhook_subscription rejects private or internal URLs. The secret is in the response once. A subscription listed with needsSecretRotation: true gets no deliveries until rotate_webhook_secret runs.

What the tools don't cover

These need the REST API or the dashboard:

• Saving custom templates (create, update, delete) and the preview / match-preview helpers. The assistant can dry-run with detect_template but not save.

• Creating, editing or deleting email sources, and connecting Gmail or Microsoft.

• One bot's log (GET /api/bots/:id/logs), the inbox, insights (profitability, calendar, leaderboard), workspace settings, username and profile visibility.

• Account export and deletion, which need a signed-in session and refuse API keys.

Errors

API errors come back as tool errors (isError: true) with the text Shippified API <status>: <message>, followed by the full JSON error body when there is one, so fields such as blockedSender or reason reach the assistant. A missing or revoked key gives Shippified API 401: Not authenticated. If SHIPPIFIED_TOKEN isn't set, authenticated tools fail before sending anything, with ShippifiedClient: token required for ….

Example prompts

• "List my orders from the last 7 days that still have no tracking number."

• "Add a manual order: Example Console Bundle from Best Buy, order BBY01-000000000001, cost $499.99."

• "Refresh tracking on order ord_mpvu9uim_aeh5t and tell me the latest carrier scan."

• "I just fixed my Hayha template. Re-parse my orders and tell me what changed."

• "Which template would parse this email? Don't import it."

• "Create a webhook subscription to https://hooks.example.com/shippified for order.shipped and order.delivered, then send it a test event."