Metadata-Version: 2.4
Name: easyship-mcp
Version: 0.4.0
Summary: MCP server for Easyship — get shipping rates and track shipments
Project-URL: Homepage, https://github.com/easyship/easyship-mcp
Project-URL: Repository, https://github.com/easyship/easyship-mcp
Project-URL: Issues, https://github.com/easyship/easyship-mcp/issues
Project-URL: Documentation, https://developers.easyship.com
Author-email: Easyship <support@easyship.com>
License-Expression: MIT
License-File: LICENSE
Keywords: easyship,mcp,rates,shipping,tracking
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Description-Content-Type: text/markdown

<!-- mcp-name: com.easyship/mcp -->
# Easyship MCP Server

MCP server for [Easyship](https://www.easyship.com) — get shipping rates and track shipments.

## Capabilities

**Tools** across 6 categories:

- **Rates** — Compare 550+ courier options with prices, delivery times, and duty estimates
- **Shipments** — Create, update, track, cancel, and manage shipments end-to-end including label purchase and document retrieval
- **Pickups** — Check available slots, schedule courier pickups, and manage existing pickups
- **Address Validation** — Validate shipping addresses
- **Billing** — View transactions and billing documents
- **Analytics** — Shipment volume trends, top destinations, courier usage, status breakdowns, and sales channel performance

## Installation

Get your API token from [Easyship Dashboard → Connect → API](https://app.easyship.com/connect/api).

Each client below offers two connection methods:

| Method | How it works | Requires Python? |
|--------|-------------|-----------------|
| **Remote** | Connects to `mcp.easyship.com` via Streamable HTTP | No |
| **Local** | Runs the `easyship-mcp` package on your machine via `uvx` | Yes |

---

### Claude Desktop

**Quit Claude Desktop** before editing config, then restart after saving.

| OS | Config file |
|----|----------------|
| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` |

Merge into the top-level `mcpServers` object (create it if missing).

**Remote:**

```json
{
  "mcpServers": {
    "easyship": {
      "type": "url",
      "url": "https://mcp.easyship.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

**Local (uvx):**

```json
{
  "mcpServers": {
    "easyship": {
      "command": "uvx",
      "args": ["easyship-mcp"],
      "env": {
        "EASYSHIP_API_ACCESS_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}
```

> Requires [uv](https://docs.astral.sh/uv/) installed on your machine.

---

### Claude Code

**Remote:**

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

**Local (uvx):**

```bash
export EASYSHIP_API_ACCESS_TOKEN="YOUR_TOKEN"
claude mcp add easyship -- uvx easyship-mcp
```

---

### Cursor

Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for global):

**Remote:**

```json
{
  "mcpServers": {
    "easyship": {
      "url": "https://mcp.easyship.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

**Local (uvx):**

```json
{
  "mcpServers": {
    "easyship": {
      "command": "uvx",
      "args": ["easyship-mcp"],
      "env": {
        "EASYSHIP_API_ACCESS_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}
```

---

### VS Code

Add to `.vscode/mcp.json` in your project:

**Remote:**

```json
{
  "servers": {
    "easyship": {
      "type": "http",
      "url": "https://mcp.easyship.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

**Local (uvx):**

```json
{
  "servers": {
    "easyship": {
      "type": "stdio",
      "command": "uvx",
      "args": ["easyship-mcp"],
      "env": {
        "EASYSHIP_API_ACCESS_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}
```

---

### Gemini CLI

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

---

### Codex CLI

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.easyship]
url = "https://mcp.easyship.com/mcp"
http_headers = { "Authorization" = "Bearer YOUR_TOKEN" }
```

---

### Other clients

For any MCP client that supports Streamable HTTP, point it at:

```
URL:    https://mcp.easyship.com/mcp
Header: Authorization: Bearer YOUR_TOKEN
```

For stdio-based clients, run `uvx easyship-mcp` with `EASYSHIP_API_ACCESS_TOKEN` set in the environment.

## Usage examples

**Get shipping rates:**
> "What are the shipping options for a 1.5kg package (30×20×15 cm) from Hong Kong to New York?"

**Track a shipment:**
> "Track shipment ESSG10006001"

**Schedule a pickup:**
> "Schedule a pickup for shipment ESSG10006001 on the earliest available date"

**Validate an address:**
> "Validate this address: 215 Clayton St, San Francisco, CA 94117"

**Analyze shipping data:**
> "What are my top shipping destinations this quarter?"

> "Which courier do I use the most?"

## API version

This server targets the Easyship API **v2024-09**.

## License

MIT
