{"id":49418379,"url":"https://github.com/groupthink-dev/auspost-blade-mcp","last_synced_at":"2026-04-29T04:12:42.189Z","repository":{"id":353470633,"uuid":"1203582846","full_name":"Groupthink-dev/auspost-blade-mcp","owner":"Groupthink-dev","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-24T02:10:02.000Z","size":103,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-24T04:16:15.152Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Groupthink-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-07T07:07:56.000Z","updated_at":"2026-04-24T02:10:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Groupthink-dev/auspost-blade-mcp","commit_stats":null,"previous_names":["groupthink-dev/auspost-blade-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Groupthink-dev/auspost-blade-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fauspost-blade-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fauspost-blade-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fauspost-blade-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fauspost-blade-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Groupthink-dev","download_url":"https://codeload.github.com/Groupthink-dev/auspost-blade-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fauspost-blade-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32410084,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T03:46:11.172Z","status":"ssl_error","status_checked_at":"2026-04-29T03:37:55.317Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-29T04:12:33.632Z","updated_at":"2026-04-29T04:12:42.175Z","avatar_url":"https://github.com/Groupthink-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# auspost-blade-mcp\n\nAustralia Post MCP server built against the **official AusPost APIs** — postage calculator, shipping, tracking, and locations in 21 tools.\n\n## Why another AusPost MCP?\n\nEvery existing Australia Post MCP has the same problem: **none of them use the actual Australia Post API.**\n\n| Existing MCP | What it actually does |\n|---|---|\n| australian-postcodes-mcp | Reads a community CSV file into SQLite. No API calls. |\n| Ninja.ai \"Australia Post\" | No public source code. Unverifiable. |\n| Shipi MCP | Commercial SaaS wrapper. AusPost is one of 15 carriers behind a proxy. |\n\n**auspost-blade-mcp** calls AusPost's `digitalapi.auspost.com.au` endpoints directly. No intermediaries, no proxies, no CSV files. You bring your own API key and get the full API surface.\n\n### What you get\n\n- **Free tier (10 tools)** — postcode search, domestic/international parcel and letter pricing, service lookup, standard box sizes, country list, post office/parcel locker locations. Requires only a free API key.\n- **eParcel tier (11 tools)** — create shipments, generate labels, track parcels, validate addresses, get contract pricing, manage orders. Requires an eParcel or StarTrack business contract.\n- **Security by default** — write operations are gated behind `AUSPOST_WRITE_ENABLED=true`. Irreversible operations (order creation) require explicit `confirm=true`. Credentials are never logged or returned in error messages.\n\n## Quick Start\n\n### 1. Get an API key\n\nRegister free at [developers.auspost.com.au](https://developers.auspost.com.au) for a PAC API key.\n\n### 2. Install\n\n```bash\nuv tool install auspost-blade-mcp\n```\n\n### 3. Configure\n\n**Claude Desktop** (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"auspost\": {\n      \"command\": \"auspost-blade-mcp\",\n      \"env\": {\n        \"AUSPOST_API_KEY\": \"your-pac-api-key\"\n      }\n    }\n  }\n}\n```\n\n**Claude Code** (`~/.claude.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"auspost\": {\n      \"command\": \"auspost-blade-mcp\",\n      \"env\": {\n        \"AUSPOST_API_KEY\": \"your-pac-api-key\"\n      }\n    }\n  }\n}\n```\n\n**With eParcel contract** (full shipping capabilities):\n\n```json\n{\n  \"mcpServers\": {\n    \"auspost\": {\n      \"command\": \"auspost-blade-mcp\",\n      \"env\": {\n        \"AUSPOST_API_KEY\": \"your-pac-api-key\",\n        \"AUSPOST_SHIPPING_API_KEY\": \"your-shipping-uuid\",\n        \"AUSPOST_SHIPPING_API_PASSWORD\": \"your-shipping-password\",\n        \"AUSPOST_ACCOUNT_NUMBER\": \"1234567890\",\n        \"AUSPOST_WRITE_ENABLED\": \"true\"\n      }\n    }\n  }\n}\n```\n\n## Tool Catalog\n\n### Free Tier (PAC + Locations) — `AUSPOST_API_KEY` only\n\n| Tool | Purpose |\n|------|---------|\n| `auspost_postcode_search` | Search postcodes and suburbs with state filtering |\n| `auspost_domestic_services` | List available domestic parcel services for a route and parcel size |\n| `auspost_domestic_calculate` | Calculate domestic parcel postage for a specific service |\n| `auspost_international_services` | List international parcel services for a country and weight |\n| `auspost_international_calculate` | Calculate international parcel postage |\n| `auspost_letter_services` | List domestic or international letter services |\n| `auspost_letter_calculate` | Calculate letter postage (domestic or international) |\n| `auspost_parcel_sizes` | Standard Australia Post box dimensions (reference data) |\n| `auspost_country_list` | All countries with 2-letter ISO codes |\n| `auspost_locations` | Find post offices, parcel lockers near a postcode |\n\n### eParcel Tier (Shipping \u0026 Tracking) — requires contract\n\n| Tool | Purpose | Gate |\n|------|---------|------|\n| `auspost_account` | Account details, products, and status | read |\n| `auspost_validate_address` | Validate suburb/state/postcode combination | read |\n| `auspost_get_shipments` | List or retrieve shipments | read |\n| `auspost_get_order` | Get order details | read |\n| `auspost_get_labels` | Check label status and get download URL | read |\n| `auspost_get_prices` | Get contract-rate pricing for items | read |\n| `auspost_track` | Track parcels by ID (max 10, rate limited 10/min) | read |\n| `auspost_create_shipment` | Create a domestic shipment | **write** |\n| `auspost_create_order` | Finalise shipments into an order (**irreversible**) | **write + confirm** |\n| `auspost_create_labels` | Generate shipping labels (PDF) | **write** |\n\n## Security Model\n\n### Credential scrubbing\n\nAPI keys and passwords are never included in tool output or error messages. Errors return AusPost error codes and human-readable messages only.\n\n### Write gates\n\nShipping write operations (`create_shipment`, `create_order`, `create_labels`) require:\n1. Shipping API credentials configured\n2. `AUSPOST_WRITE_ENABLED=true` in environment\n\n### Confirm gates\n\n`auspost_create_order` requires `confirm=true` parameter. Orders cannot be cancelled, deleted, or voided after creation per AusPost API constraints.\n\n### Bearer auth (HTTP transport)\n\nWhen running in HTTP mode (`AUSPOST_MCP_TRANSPORT=http`), set `AUSPOST_MCP_API_TOKEN` to require `Authorization: Bearer \u003ctoken\u003e` on all requests.\n\n### Test sandbox\n\nSet `AUSPOST_SHIPPING_TEST_MODE=true` to use AusPost's test environment. Test requests return sample data and do not create real shipments.\n\n## Configuration Reference\n\n| Variable | Required | Secret | Default | Purpose |\n|----------|----------|--------|---------|---------|\n| `AUSPOST_API_KEY` | Yes | Yes | — | PAC + Locations API key (free) |\n| `AUSPOST_SHIPPING_API_KEY` | No | Yes | — | Shipping API key (eParcel contract) |\n| `AUSPOST_SHIPPING_API_PASSWORD` | No | Yes | — | Shipping API password |\n| `AUSPOST_ACCOUNT_NUMBER` | No | No | — | 10-digit eParcel account number |\n| `AUSPOST_WRITE_ENABLED` | No | No | `false` | Enable write operations |\n| `AUSPOST_SHIPPING_TEST_MODE` | No | No | `false` | Use AusPost test sandbox |\n| `AUSPOST_MCP_TRANSPORT` | No | No | `stdio` | Transport: `stdio` or `http` |\n| `AUSPOST_MCP_API_TOKEN` | No | Yes | — | Bearer token for HTTP transport |\n\n## Architecture\n\n```\nsrc/auspost_blade_mcp/\n├── server.py       FastMCP instance, 21 @mcp.tool definitions\n├── client.py       PACClient + ShippingClient (httpx async)\n├── formatters.py   Token-efficient output (pipe-delimited, null-omitted)\n├── models.py       Config parsing, security gates, constants\n├── auth.py         Bearer token middleware for HTTP transport\n└── __main__.py     python -m entry point\n```\n\n### API coverage\n\n| AusPost API | Tier | Endpoints | Auth |\n|-------------|------|-----------|------|\n| PAC (Postage Assessment Calculator) | Free | 10 endpoints | `AUTH-KEY` header |\n| Locations | Free | Postcode-based search | `AUTH-KEY` header |\n| Shipping \u0026 Tracking | Contract | 12 endpoints | HTTP Basic + Account-Number |\n\n### Token efficiency\n\nOutput is designed for LLM consumption, not human reading:\n- Pipe-delimited compact format for lists\n- Null fields omitted entirely\n- Tracking events capped to last 5 per item\n- No JSON wrapping — structured plaintext\n\n## Development\n\n```bash\ngit clone https://github.com/Groupthink-dev/auspost-blade-mcp.git\ncd auspost-blade-mcp\nmake install-dev\nmake test        # unit tests (mocked, no API key needed)\nmake test-cov    # with coverage\nmake test-e2e    # live API tests (requires AUSPOST_API_KEY)\nmake check       # lint + type-check\nmake run         # start server (stdio)\n```\n\n## AusPost API Limitations\n\n- **No webhooks** — tracking is polling-based. `auspost_track` is rate-limited to 10 requests/minute, max 10 IDs per call.\n- **No mixed tracking** — cannot combine Australia Post and StarTrack tracking IDs in a single call.\n- **Orders are final** — once created via `auspost_create_order`, orders cannot be cancelled, deleted, or voided.\n- **Labels max 250** — synchronous label generation supports up to 250 parcels per request.\n- **Locations API** — the new Locations API requires partner agreement for bulk export. This MCP uses the PAC postcode search for location data, which returns geocoded suburbs.\n\n## Stallari Marketplace\n\nThis MCP is published as a **certified** provider in the [Stallari Marketplace](https://stallari.ai). See `stallari-plugin.yaml` for the full manifest including credential configuration, test endpoints, and contract mappings.\n\nContract: `logistics-v1` (renamed from `postal-v1` in pack-spec 2.0.0)\n\n- Marketplace listing: https://stallari.ai\n- Stallari platform repo: https://github.com/Groupthink-dev/stallari\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupthink-dev%2Fauspost-blade-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgroupthink-dev%2Fauspost-blade-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupthink-dev%2Fauspost-blade-mcp/lists"}