omada

A collection of network analysis tools for the home lab. The repository is a single monorepo that currently houses the Omada Controller MCP server — a Model Context Protocol server for inspecting, diagnosing, RF scanning, and optimizing EAPs (access points) on a self-hosted TP-Link Omada Controller.

Tools

Omada Controller MCP server

Lets AI agents query the Omada Controller API (device inventory, client roaming/disconnect timelines, AP health, RF scans) and optimize Wi-Fi in a change-measure-validate loop, with an allow-list API firewall and dry-run safety. Includes an interactive setup wizard and two agent skills: device-network-dossier for per-device behavior analysis and wifi-site-audit for whole-site Wi-Fi audits with scorecards and a prioritized improvement plan.

See omada-mcp-server/README.md for setup, usage, and the setup wizard.

How it works: OpenAPI → tools, filtered by an allow list

The controller exposes its full REST API as an OpenAPI document (openapi.json, or a live URL). At startup the server loads that document and generates one MCP tool per endpoint with FastMCP, so the tool set always matches the controller's actual API version — no hand-maintained wrappers, and the same code adapts to different controller versions and firmware as their schemas evolve.

Two mechanisms keep the surface small and cheap:

1. Allow list. Only endpoints matching the configured patterns become tools. Each route is either a safe, read-only diagnostic operation or a deliberately scoped mutation that should run with the MCP_DRY_RUN guardrail. This is the firewall that keeps the agent away from sensitive areas (switch/gateway management, vouchers, VPN configs, user accounts).

2. Description sanitization. Every tool/parameter description is cleaned before it is handed to the model: HTML tags are stripped, whitespace is normalized, and the controller's trailing boilerplate (permission lists, error-code tables) is removed. Regex pattern hints that are not valid ECMA-262 are dropped so LLM providers accept the generated schemas.

Why both matter: exposing the whole API would generate on the order of a thousand tools, each with verbose descriptions — a massive amount of context pushed into every conversation, costing tokens on each request and distracting the model. Filtering to the handful of EAP/diagnostics routes and slimming their descriptions keeps the toolset to a few dozen tools with crisp help text, cutting token consumption by roughly an order of magnitude.

The allow list is defined in omada-mcp-server/wlanoptimization.txt (or via ALLOWED_ENDPOINTS inline, falling back to built-in defaults). It uses fnmatch wildcards, one pattern per line, # for comments. The shipped file is trimmed for Wi-Fi/EAP work. Because it is just patterns, you can swap in a different surface without touching code — for example, a switch-management allow list:

# Switch / port management variant
/openapi/v1/{omadacId}/sites/{siteId}/switches*
/openapi/v1/{omadacId}/sites/{siteId}/ports*
/openapi/v1/{omadacId}/sites/{siteId}/switch-qos*
/openapi/v1/{omadacId}/sites/{siteId}/stacks*

Point ALLOWED_ENDPOINTS_FILE at that file and restart the server to trade the EAP toolset for a switch toolset.

mcp.sh

Quick lifecycle control for the MCP server:

./mcp.sh start   # start the server detached (setsid), log to omada_mcp.log
./mcp.sh stop    # gracefully stop the server (SIGTERM), force-kill after 8s if needed

Requires the project's .venv to be set up (run the setup wizard first).

Layout

mcp.sh                      # start/stop the MCP server
omada-mcp-server/           # the MCP server itself (see its README)
  scripts/setup_omada.py    # interactive setup wizard
  skills/device-network-dossier/  # per-device network dossier skill
  skills/wifi-site-audit/         # whole-site Wi-Fi audit skill
specs/                      # design documents

Contributing

All code, documentation, and specs in this repository must be written in English. Python is the runtime for the MCP server (see the server README for its conventions).