How to Connect Gemini CLI to the Easyship MCP Server

This article explains how to set up the Easyship MCP server in Gemini CLI so you can manage shipping tasks, including comparing rates, creating shipments, buying labels, scheduling pickups, and tracking deliveries all through natural language.

Before You Begin

You'll need:

• Gemini CLI installed on your machine
• Access to your Easyship Dashboard
• An Easyship account (API access is available on all plans at no extra cost)

Step 1: Get Your Easyship API Token

1. Go to your Easyship Dashboard and click Connect
2. Click New Integration
3. Scroll down to API Integration
4. Under Integration Type, select I am developing a custom integration
5. Name the key Easyship MCP for easy reference
6. Keep the default version 2024-09 and click Connect
7. On the next page, click Access Token and copy it using the copy button

Required scopes: Your API token must include the following scopes. Missing scopes will cause some tools to fail while others continue to work.

public.shipment:read              public.shipment:write
public.label:write                public.pickup:read
public.pickup:write               public.address_validation:write
public.address_validation_domestic:write
public.shipment_document:read     public.transaction_record:read
public.analytics:read             public.rate:read
public.track:read

You can check and update scopes at any time in Dashboard → Connect → API without creating a new token.

Step 2: Add the Easyship MCP Server to Gemini CLI

Choose either the one-command install or the manual method.

Option A: Install via extensions (recommended)

bash

gemini extensions install https://github.com/easyship/easyship-mcp-plugin

Option B: Add manually

gemini mcp add --transport http easyship \
  https://mcp.easyship.com/mcp \
  --header 'Authorization:Bearer YOUR_TOKEN'

Replace YOUR_TOKEN with the API token you copied in Step 1.

Note: The extensions install command installs the full Easyship AI toolkit from GitHub, which may include additional configuration beyond the MCP server. The manual method connects the MCP server directly. Both give you the same Easyship tools in your session.

Security: Never share your API token in the chat window. If you accidentally paste it in a prompt, revoke and rotate your API key immediately in the Easyship Dashboard under Connect → API.

Step 3: Verify the Connection

Run the following command to confirm the Easyship MCP server is registered:

bash

gemini mcp list

You should see Easyship listed with a connected status. Confirm all tools are successfully loaded.

If easyship doesn't appear, remove and re-add the server:

bash

gemini mcp remove easyship
gemini mcp add --transport http easyship \
  https://mcp.easyship.com/mcp \
  --header 'Authorization:Bearer YOUR_TOKEN'

Step 4: Try It Out

Start a Gemini CLI session and try a prompt like:

I want to ship a parcel from New York, USA to Toronto, Canada. Origin: 350 5th Avenue, New York, US 10001. Destination: 220 Yonge Street, Toronto, ON, Canada M5B 2H1. Parcel: 1.98 lb, 6 × 4 × 2 cm. Item: Business documents, quantity 1, HS Code 4911.99, declared value $1.00 USD, category documents, DDU. Show me the cheapest and best value shipping options with delivery times and courier names.

For a full list of available tools and workflows, see the Easyship MCP Developer Docs.

FAQs

Can I use an existing API token, or do I need a new one? 

You can use an existing token from your Easyship account. Just make sure it has all the required scopes listed in Step 1. If some scopes are missing, certain tools will fail while others work.

What's the difference between the extensions install and the manual method? 

The gemini extensions install command installs the full Easyship AI toolkit from GitHub, which may include additional skills and configuration beyond the MCP server. The gemini mcp add command connects only the MCP server directly. Both give you the same Easyship tools in your session.

What if "easyship" doesn't appear in gemini mcp list? 

Double-check the server URL (https://mcp.easyship.com/mcp) and your API token. For the manual method, make sure the --header flag uses Authorization:Bearer YOUR_TOKEN with no space after the colon. Remove and re-add the server with:

bash

gemini mcp remove easyship

gemini mcp add --transport http easyship https://mcp.easyship.com/mcp --header 'Authorization:Bearer YOUR_TOKEN'

What if not all tools are loaded?

• Verify your API token is valid and active
• Run gemini mcp remove easyship and add it again
• Check your network connection
• Make sure you're connecting to https://mcp.easyship.com/mcp

Why is my API token not working? 

Check the scopes for your token in the Easyship Dashboard under Connect → API. A token might work for some actions but fail for others depending on which scopes it has. For full access to all tools, enable all the scopes listed in Step 1.

What happens if I don't grant all the required scopes? 

Only the tools that match your granted scopes will work. Other tools will return an error, and the agent will tell you which scope is needed. You can update scopes in the Easyship Dashboard without creating a new token.

Do I need to pay for the API token? 

No. Easyship provides API access across all plans at no extra cost. If you exceed the included API limits for your plan, overage fees may apply. See [pricing plans and included limits].

Can I use the same token across multiple clients (Gemini CLI, Cursor, Claude, etc.)? 

Yes. The same API token works across any MCP client. Be mindful of rate limits and avoid running conflicting operations (like editing the same shipment from two clients at once).

Need Further Assistance?

If you're experiencing an error that isn't covered above, submit a bug report. Include the tool name, error code, and request ID from the error response - these help us diagnose the issue faster.