Skip to main content
Glama
Canada Post MCP Server

Canada Post MCP Server

by richardsondx

🍁 UNOFFICIAL Canada Post MCP Server

UNOFFICIAL. This project is not affiliated with, endorsed by, or connected to Canada Post Corporation / Postes Canada. Canada Post publishes no official MCP server. This is a community project built by Canadians, for Canadians, in red and white.

A Model Context Protocol server that gives AI agents four Canada Post tools: parcel tracking, shipping rates, post office finder, and MyMail (local only, opt-in).

Tools

Tool

What it does

track_parcel

Track a parcel by tracking number. Live status from Canada Post public tracking, or an honest error when Canada Post blocks the request.

get_rates

Get shipping rates for a route. Live rates need free Developer Program credentials; without them it links the public Find a Rate calculator and never invents a rate.

find_post_office

Find post offices near a place or postal code. Every result has a real address.

list_mymail

List incoming mail from MyMail. Local only, opt-in, mock mode for tests. Never logs in.

Related MCP server: USA Logistics MCP

Install

npm install
npm run build
npm start

That is the one start command. The server runs on stdio. Add it to your MCP client:

{
  "mcpServers": {
    "canada-post": {
      "command": "node",
      "args": ["/path/to/canada-post-mcp/dist/server.js"]
    }
  }
}

Config

Copy .env.example to .env. No values are real. Leave blank to use public routes only.

cp .env.example .env

Variable

Use

CANADA_POST_DEVPORTAL_KEY

Developer Portal API Key for your app. Preferred route, used first.

CANADA_POST_DEVPORTAL_SECRET

Developer Portal API Secret for your app. Never commit this.

CANADA_POST_CUSTOMER_NUMBER

Your Canada Post customer number. Needed for commercial rates.

CANADA_POST_CONTRACT_NUMBER

Your Canada Post contract number, if you have one. Needed for some rates.

CANADA_POST_API_KEY

Legacy Developer Program key. Authenticated fallback for Track, Rating, and Post Office APIs.

CANADA_POST_API_PASSWORD

Legacy Developer Program password for the key above.

CANADA_POST_MyMAIL_ENABLED

Set true only on your own machine to enable MyMail. Default off.

CANADA_POST_MyMAIL_MOCK

Set true with the above for mock sample data. No login.

CANADA_POST_MyMAIL_EXPORT_FILE

Path to a MyMail JSON file you saved yourself from the Canada Post app.

Get free Developer Program credentials at the Canada Post Developer Program. For the preferred route, create an app in the Canada Post Developer Portal, subscribe it to Tracking and Rating, and copy its API Key and API Secret into .env. The server gets a token with OAuth2 client credentials, scope merchant, then calls Tracking v1 and Rating v1. A Test app returns stubbed data, not live parcel data. A production app returns live data.

Examples

Track a parcel (16-digit domestic number, or a 13-character code ending in CA):

{ "tracking_number": "1234567890123456" }

Get rates from Toronto to Vancouver for a 1 kg parcel:

{
  "origin_postal_code": "M5G 1N6",
  "destination_postal_code": "V6B 1A1",
  "weight_kg": 1,
  "length_cm": 30,
  "width_cm": 20,
  "height_cm": 10
}

Find post offices near downtown Toronto:

{ "query": "Toronto", "radius_km": 5 }

List MyMail (mock mode):

{ "limit": 5 }

MyMail: local only, opt-in, break risk

MyMail shows incoming Lettermail, Personalized Mail, and Neighbourhood Mail in the Canada Post app. This server treats MyMail as local only:

  • MyMail is off by default. It needs explicit env config to run at all.

  • With no config, list_mymail fails cleanly with a clear message.

  • Mock mode returns labelled sample items. No live login happens in tests or in this repo.

  • This server never stores a password or token, never logs in to a Canada Post account, and never scrapes with a hardcoded account.

  • Break risk: MyMail has no public API. If Canada Post changes its app or site, the MyMail path can break without warning. Live MyMail proof is a user run on their own machine after publish, not part of this repo.

Honest data policy

  • A tool returns a real status, rate, or address only when Canada Post actually returned it.

  • When Canada Post blocks a public request (the public tracking JSON endpoint returned HTTP 403 from this build machine on 2026-11-11), the tool says so, names the source URL, and invents nothing.

  • The post office finder without API credentials uses a small recorded directory of real downtown Toronto offices, verified 2026-11-11 from canadapost.ca listings, and labels it as recorded data.

  • See research.md for every route, source link, live observation, and block.

Check CLI

./check.sh --help
./check.sh doctor    # node, deps, build, credential scan
./check.sh launch    # start the server
./check.sh drive     # list tools, run one track / rates / finder call
./check.sh evidence  # write results to evidence/
./check.sh cleanup   # stop only what the run started

Tests

npm test

Tests cover tool schemas, tracking-number validation, postal code validation, and the MyMail mock path with no live login. The live smoke test is skipped cleanly when Canada Post blocks it, and the skip is recorded in EVIDENCE.md.

Official Canada Post links

Disclaimer

This project is UNOFFICIAL. It is not affiliated with, endorsed by, sponsored by, or connected to Canada Post Corporation / Postes Canada. "Canada Post", "Postes Canada", "MyMail", "Xpresspost", and "Lettermail" are trademarks of Canada Post Corporation. This server uses public web routes and the official Developer Program APIs with the user's own credentials. Use it at your own risk, and confirm rates, delivery dates, and post office hours on the official Canada Post site before you act on them.

License

MIT. See LICENSE.

Available Tools

4 tools
find_post_officeA

Find Canada Post post offices near a place or postal code. Each result has a real address. Without API credentials it uses a recorded directory of real downtown Toronto offices, labelled as recorded data.

Inputs: query, radius_km, postal_code.

get_ratesA

Get Canada Post shipping rates for a parcel route. Needs official Developer Program credentials in env for live rates; without them it reports honestly and links the public Find a Rate calculator. Never invents a rate.

Inputs: width_cm (required), height_cm (required), length_cm (required), weight_kg (required), +2 more.

list_mymailA

List incoming mail from Canada Post MyMail. LOCAL ONLY and OPT-IN. Returns mock sample items only when CANADA_POST_MyMAIL_ENABLED=true and CANADA_POST_MyMAIL_MOCK=true, or items from a local export file you saved yourself. Fails cleanly when not configured. Never logs in.

Inputs: limit.

track_parcelA

Track a Canada Post parcel by tracking number. Returns the live status from Canada Post public tracking, or an honest error when Canada Post blocks the request. Never invents a status.

Inputs: tracking_number (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a clearly distinct resource and action: parcel tracking, rate quotes, post office lookup, and MyMail inbox listing. There is no plausible overlap that would cause an agent to misselect, and the descriptions reinforce the boundaries (live API vs. recorded data vs. local mock).

    Naming Consistency4/5

    All four tools follow a snake_case verb_noun pattern (track_parcel, get_rates, find_post_office, list_mymail), which is predictable and readable. The only minor deviation is list_mymail, where the object is a brand name rather than a plural noun like list_mail_items.

    Tool Count4/5

    Four tools is on the lean side but each maps to a real, non-redundant Canada Post capability, so nothing feels padded. It only falls short of 5 because the surface is thin enough that a user might reasonably expect adjacent operations (e.g. label creation or address validation) to be present.

    Completeness3/5

    The set covers the read-only lookups well (tracking, rates, offices, inbox), but there is no way to create a shipment or buy a label, no postal-code/address validation, and no delivery-standard/estimated-transit lookup. These are notable gaps for a server framed as Canada Post parcel services, even if the honest-fallback design suggests intentional read-only scope.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers