Skip to content

ShipHero MCP

The ShipHero MCP is the easiest way to connect an AI client to ShipHero. It lets supported clients query your ShipHero account without requiring you to manually write GraphQL, manage Public API tokens, or install the full skill package.

ShipHero MCP works anywhere MCP is supported, including:

ProductSupported clients
Claude ChatWeb and Desktop
Claude CoWorkWeb and Desktop
Claude CodeWeb, Desktop, and CLI
ChatGPTWeb, Desktop, and CLI
Other MCP clientsAny product with MCP support

Use the MCP for questions like:

  • What’s the current inventory level for SKU ABC-123?
  • Show me orders with an address hold.
  • Show shipments created yesterday.
  • List purchase orders expected to arrive this week.
  • Show returns created today.

If you grant read-write access, you can also ask it to make changes, like:

  • Order tags: Add order tag abc to unfulfilled orders with SKU ABC-123.
  • Holds: Remove the address hold from order 123456.
  • Order editing: Add one GIFT-WRAP to order #10582.
  • Kits: Turn existing SKU SUMMER-BUNDLE into a kit containing two shirts and one cap.
  • Shipments: Create a shipment for order #10582 with UPS tracking number 1Z999....
  • 3PL billing: Charge Acme $35 for relabeling 100 units.
  • Products: Add an image of a plain white t-shirt for product T-SHIRT-WHITE.

The MCP is designed for simple ShipHero queries and updates. It is not intended for building full integrations or generating complex custom application code.

Warning

Granting read-write access lets the MCP client create, update, or delete data in your ShipHero account, including products, orders, shipments, and more. Only grant read-write access to clients and prompts you trust, and review the changes it makes.

Installation

Our MCP server URL is:

https://mcp.shiphero.com/mcp

Installation steps vary by AI client and subscription type. Follow your AI client’s documentation, or ask your AI client to help you configure the connection.

When you add the ShipHero MCP, your client opens a ShipHero authorization flow. Log in with your ShipHero credentials and select the access level (read-only or read-write) you want to grant to the client. You can change this later by reconnecting the MCP and going through the authorization flow again.

ShipHero authorization flow showing the access level selector

Pick your client below to expand its setup steps.

Claude
Claude calls MCP servers Connectors. See Claude’s official custom connector documentation.
ChatGPT and Codex

Warning

If you have an earlier ShipHero MCP version installed, please uninstall it first.

See OpenAI’s official Developer mode and MCP apps in ChatGPT.

ChatGPT calls MCP servers Plugins.

Enterprise accounts

On Enterprise accounts, account owners need to add the MCP configuration through the ChatGPT organization setup.

Personal and Team accounts

On Personal or Team accounts, you can add the ShipHero MCP through ChatGPT Web, your config file, or the CLI. Adding it through ChatGPT Web makes it available in all ChatGPT and Codex clients connected to your account. Adding it through the config file or CLI makes it available only to local Codex clients that share that configuration.

ChatGPT Web

Warning

Enable Developer mode before adding the ShipHero MCP.

The easiest way to add the MCP is through https://chatgpt.com. Log in to your account, then go to Settings > Plugins > Browse Plugins > Add, and use the MCP server URL https://mcp.shiphero.com/mcp.

Config file

Add the following to your ChatGPT/Codex configuration (official documentation):

[mcp_servers.shiphero]
url = "https://mcp.shiphero.com/mcp"
scopes = ["read:public-api", "read-write:public-api"]

[mcp_servers.shiphero.oauth]
client_id = "00ks8TNFn5J9SrqePsRSHKmiakONdWjU"
callback_port = 41592

Restart your app afterwards.

CLI
  1. Add the ShipHero MCP server:

    codex mcp add shiphero --url https://mcp.shiphero.com/mcp
  2. Codex opens a login page. The page currently returns an error because of a Codex bug.

  3. Return to the terminal and press Ctrl+C.

  4. Log in again with the required scopes:

    codex mcp login shiphero --scopes read:public-api,read-write:public-api

    When the login page opens, authorize the connection.

  5. Open Codex and test the ShipHero MCP.

Others

See your AI client’s documentation for MCP setup instructions. You can also ask the client to add the ShipHero MCP and point it to this page.

The ShipHero MCP server URL is https://mcp.shiphero.com/mcp.

The server requires OAuth. Choose a setup option below.

CIMD
To request support for another agent via CIMD, email mcp@shiphero.com with the agent’s name and its externally hosted Client ID Metadata Document (CIMD) URL. The URL must be publicly accessible over HTTPS and return the agent’s JSON client metadata.
Client ID

For clients that use a preconfigured OAuth client ID, use the following settings:

  • OAuth Client ID: 00ks8TNFn5J9SrqePsRSHKmiakONdWjU
  • OAuth Callback port: 41592
  • Scopes: read:public-api read-write:public-api
MCP stdio command

Alternatively, you can fall back to a stdio MCP configuration:

npx -y mcp-remote@latest https://mcp.shiphero.com/mcp 41592 --transport http-only --static-oauth-client-info "{\"client_id\":\"00ks8TNFn5J9SrqePsRSHKmiakONdWjU\"}" --static-oauth-client-metadata "{\"scope\":\"read:public-api read-write:public-api\"}"

Troubleshooting

If the ShipHero MCP doesn’t show up or doesn’t respond right after you add it, restart your AI client. Most clients only pick up newly added MCP servers after a full restart.

If authorization fails with an error page like the one below, click See details for this error. The information behind that link is important — share it with ShipHero Support or when asking for help in the Community so we can diagnose the problem quickly.

ShipHero authorization error page with the “See details for this error” link highlighted

Still stuck? Come ask in the ShipHero Community. We’re happy to help.

Usage

After installation and authorization, ask your AI client a ShipHero question:

Get my last 50 ShipHero orders.

Keep prompts specific. Ask for the exact object, date range, SKU, order number, warehouse, or status you need. Specific prompts use fewer API credits and return better answers.

API Credits

MCP requests use a separate AI Toolkit credit pool. They do not reduce the credits available for standard Public API requests.