parcelapp-mcp

An MCP server for Parcel, the macOS and iOS delivery tracking app. It lets a model read your deliveries, add new ones, and look up the carrier codes the API needs, over the small external API that Parcel premium accounts get.

The server is deliberately thin. The upstream API is tiny and heavily rate limited, so the value added here is not abstraction, it is legibility: carrier codes resolved to names, numeric status codes resolved to text, required fields validated locally before a request is spent, and every result carrying how much of the rate-limit budget is left.

It runs two ways. Over stdio it is a personal server reading your key from the environment. Over HTTP the key travels with each request, so one deployment serves several people without ever holding anyone's credential.

✨ Features

🚀 Quickstart

You need a Parcel premium account and an API key from web.parcelapp.net.

export PARCEL_TOKEN="your-key"
uvx --from git+https://github.com/obeone/parcelapp-mcp parcelapp-mcp

That runs the server on stdio. In practice you point an MCP client at it rather than running it by hand: see Configuration.

📦 Installation

With uvx, no checkout

uvx --from git+https://github.com/obeone/parcelapp-mcp parcelapp-mcp

From a local clone

git clone https://github.com/obeone/parcelapp-mcp
cd parcelapp-mcp
uv sync
uv run parcelapp-mcp

With Docker, for the HTTP transport

The image holds no key. Every caller sends their own, so the container is safe to share.

docker build -t parcelapp-mcp --build-arg VERSION="$(uv version --short)" .
docker run -d --name parcel -p 8000:8000 parcelapp-mcp

VERSION only stamps the OCI label; the build works without it.

curl -sS -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'X-Parcel-Token: your-key' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

127.0.0.1 rather than localhost on purpose: localhost resolves to ::1 first on macOS, and -p 8000:8000 publishes on IPv4 only, so the connection is refused for a reason that has nothing to do with this server.

⚙️ Configuration

Environment

Every variable has a command-line equivalent: --transport, --host, --port, --path.

Sending the key over HTTP

Two headers are accepted, checked in this order:

X-Parcel-Token: your-key
Authorization: Bearer your-key

If neither is present the server falls back to its own environment, which is what makes the same code work on stdio. When nothing supplies a key, the error names both routes rather than saying "unauthorised".

Claude Code

claude mcp add parcel -e PARCEL_TOKEN=your-key -- \
    uvx --from git+https://github.com/obeone/parcelapp-mcp parcelapp-mcp

Claude Desktop

In claude_desktop_config.json:

{
  "mcpServers": {
    "parcel": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/obeone/parcelapp-mcp",
        "parcelapp-mcp"
      ],
      "env": { "PARCEL_TOKEN": "your-key" }
    }
  }
}

Keeping the key out of a config file

On macOS, envchain stores it in the Keychain and injects it only into the wrapped command:

envchain --set parcel PARCEL_TOKEN

{
  "mcpServers": {
    "parcel": {
      "command": "envchain",
      "args": [
        "parcel",
        "uvx",
        "--from",
        "git+https://github.com/obeone/parcelapp-mcp",
        "parcelapp-mcp"
      ]
    }
  }
}

🧰 Tools

search_carriers is the one to call first: add_delivery needs an internal carrier code such as lp (La Poste) or chrono (Chronopost), and it reports which carriers additionally require a postcode or an email.

Resource

parcel://deliveries/{filter_mode} exposes the same listing for passive reading, with active or recent. It shares the cache and the hourly budget with list_deliveries, so consulting it cannot quietly drain the allowance.

The rate-limit block

Every delivery result carries one:

{
  "limit": 20,
  "per": "hour",
  "spent_by_this_server": 3,
  "remaining_at_most": 17,
  "note": "Counted locally: Parcel returns no rate-limit headers. ..."
}

It says remaining_at_most rather than remaining on purpose. Parcel publishes no counter and returns no rate-limit headers, so this is counted here: it sees only the requests this process sent since it started. The Parcel app on your phone spends from the same budget, invisibly.

⚠️ Limitations

These come from the upstream API, not from this server.

The HTTP mode has one of its own: it does not authenticate callers. It forwards whatever key it is given and partitions its cache by a fingerprint of that key, so callers cannot see each other's parcels, but anyone who can reach the port can use it as a relay with their own key. Put it behind something that decides who may connect before exposing it beyond localhost.

🧪 Development

uv sync
uv run pytest        # 80 tests, no network
uv run ruff check
uv run ruff format
uv run mypy          # strict

The suite mocks the upstream with respx, so it costs nothing from either rate limit. Three live scripts remain as manual checks against the real API, all read-only, none of which calls add_delivery:

envchain parcel uv run scripts/smoke_test.py   # in process
envchain parcel uv run scripts/stdio_test.py   # through a real MCP client
envchain parcel uv run scripts/http_test.py    # against a running HTTP server

CI runs lint and type checks once, then the suite on Python 3.10 through 3.13.

🏗️ Architecture

flowchart TB
    subgraph clients["Clients"]
        A["Claude Desktop, Claude Code"]
        B["Any MCP client over HTTP"]
    end

    subgraph server["parcelapp-mcp"]
        C["server.py: 3 tools, 1 resource,<br/>key resolution, code tables"]
        D["client.py: HTTP, per-key cache,<br/>rate-limit counters"]
        C --> D
    end

    subgraph upstream["api.parcel.app"]
        E["deliveries<br/>20 per hour"]
        F["add-delivery<br/>20 per day"]
        G["supported_carriers.json<br/>no limit"]
    end

    A -- "stdio, key from env" --> C
    B -- "HTTP, key per request" --> C
    D --> E
    D --> F
    D --> G

Two rules hold this together. add_delivery checks the carrier code and any required postcode or email against the cached catalogue before touching the network, because a rejected request costs the same as a successful one. And everything cached or counted is keyed by a fingerprint of the caller's API key, so a shared HTTP deployment cannot serve one person's parcels to another.

📝 License

MIT, see LICENSE. Not affiliated with Parcel or its developer.

Made by Grégoire Compagnon (obeone)