aussiebb-mcp

An MCP server for Aussie Broadband NBN diagnostics — the same tests the MyAussie portal offers under "All Service Tests" (Check/Kick Connection, Loopback, NTD Status/Reset), plus test history, NBN outages, speed test results, and fault tickets. Give your AI assistant the other half of the "is the internet down?" question: when the LAN view says the WAN is dead, these tools say whether it's the ISP/NBN side.

Unofficial API — use at your own risk. This project is not affiliated with or endorsed by Aussie Broadband. It talks to the undocumented MyAussie JSON API (myaussie-api.aussiebroadband.com.au) — the same API the portal SPA and the Home Assistant integration (pyaussiebb) use — which can change or break without notice. Two tools (kick_connection, ntd_reset) deliberately disconnect your service; they refuse to run without confirm=true, but understand what they do before granting it. Your portal credentials go into an env file — protect it accordingly, and use the API respectfully.

Tools

Services are addressed by a site alias (optional, from AUSSIEBB_SERVICES), a raw numeric service_id, or 'all'. Read-only tools default to all; test-running tools require exactly one service.

Tool	Params	Notes
list_services	service_type='NBN'	ids, aliases, plan/speed/POI, WAN IPs
list_diagnostics	service='all'	what AussieBB offers, destructive flags
check_connection	service='all'	instant ISP-side "is it connected" — run this first
ntd_status	service, wait=True, timeout_s=180	~2 min; link state, uptime, flap count (dropout evidence)
loopback_test	service, wait=True, timeout_s=180	~2 min; two-way data proof to the NBN box/node
test_result	service, test_id	fetch one run's status/result (for wait=False flows)
test_history	service='all', limit=10	recent runs with pass/fail summaries
service_outages	service='all'	current + scheduled + resolved NBN/ABB outages
speed_test_results	service='all'	ABB-recorded speed tests
list_faults	include_details=True	open fault tickets (account-wide)
kick_connection	service, confirm=False	DESTRUCTIVE — drops the session (modem swaps); refuses without confirm=true
ntd_reset	service, confirm=False, wait, timeout_s	DESTRUCTIVE — reboots the NBN box; refuses without confirm=true
run_diagnostic	test, service, wait, timeout_s, confirm	escape hatch for any test by name; destructive names still gated

Failed or unfinished tests carry AussieBB's own "report a fault if" guidance in the response — the API's failure payloads are otherwise bare.

Quick start (stdio)

Most users need exactly two env vars — services are discovered live from the account:

// e.g. Claude Desktop claude_desktop_config.json / Claude Code .mcp.json
{
  "mcpServers": {
    "aussiebb": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/aussiebb-mcp", "aussiebb-mcp", "--stdio"],
      "env": {
        "AUSSIEBB_USERNAME": "you@example.com",
        "AUSSIEBB_PASSWORD": "..."
      }
    }
  }
}

Prefer an env file over inline credentials where your client supports it (uv run --env-file ...). stdio mode has no network surface and skips bearer auth — the client owns the process.

Configuration

Env var	Default	Purpose
AUSSIEBB_USERNAME / AUSSIEBB_PASSWORD	(empty)	MyAussie portal login. Tools error clearly when unset.
AUSSIEBB_SERVICES	(empty)	Optional alias=id map, e.g. home=1000001,office=1000002. Aliases become tool vocabulary (and are baked into the server instructions); without it, services are discovered live.
AUSSIEBB_SESSION_FILE	~/.local/state/aussiebb-mcp/session.json	Where the ~1-year login cookie persists (0600, dir 0700).
PORT	8329	HTTP listen port.
MCP_BEARER_TOKEN	(empty)	Required in HTTP mode; server refuses to start without it. Not used in --stdio mode.

HTTP mode (container)

The bundled Containerfile builds a Streamable HTTP server at /mcp (stateless). HTTP mode refuses to start without MCP_BEARER_TOKEN; clients authenticate with Authorization: Bearer <token>.

podman build -t aussiebb-mcp .   # or: docker build -t aussiebb-mcp .
podman run -d --name aussiebb-mcp -p 8329:8329 -v abb-state:/data \
  -e AUSSIEBB_USERNAME=you@example.com -e AUSSIEBB_PASSWORD=... \
  -e AUSSIEBB_SESSION_FILE=/data/session.json \
  -e MCP_BEARER_TOKEN=some-long-random-token \
  aussiebb-mcp

Persist the session file across restarts (the volume above) — the login endpoint rate-limits hard, and the cookie lives about a year. aussiebb_mcp.healthcheck does a full HTTP round-trip to /mcp (the 401 counts as alive); wire it to your container healthcheck. Terminate TLS at a reverse proxy — the server itself speaks plain HTTP.

API notes (hard-won)

• Login (POST myaussie-auth.../login) returns a myaussie_cookie valid ~1 year. The endpoint is aggressively rate-limited (429) — the client persists the session to disk, logs in lazily, re-logs-in at most once per request on 401/419 (invalidating in memory only, so a failed re-login can't destroy a persisted cookie), and serializes login behind a lock. Never retry-loop a 429.
• Check and Kick share one URL (/broadband/{sid}/connection): GET = harmless check, POST = drops the session. Dispatch is strictly name → (path, method) via the TESTS registry; the link field from the available-tests response is never blind-POSTed.
• Async tests return a record immediately (status: WaitingToBeQueued) and are polled at GET /tests/{sid}/{test_id} through InProgress to Completed (result: Passed|Failed), ~115 s total in practice.

Testing

# Tier 1+2 — pure units + mocked-transport client/server logic
# (no network, no credentials — fully fabricated fixtures)
uv run --extra test pytest tests/ --ignore=tests/test_integration.py -v

# Tier 3 — live read-only API tests (login, services, check_connection,
# history, outages; starts no test runs, changes nothing)
AUSSIEBB_TEST=1 AUSSIEBB_USERNAME=... AUSSIEBB_PASSWORD=... \
    uv run --extra test pytest tests/test_integration.py -v

# optional: one live NTD Status run (~2 min, shows up in portal history)
AUSSIEBB_TEST=1 AUSSIEBB_TEST_RUN=1 AUSSIEBB_USERNAME=... AUSSIEBB_PASSWORD=... \
    uv run --extra test pytest tests/test_integration.py -v

kick_connection and ntd_reset are never exercised by any automated tier.

License

MIT