TP-Link Omada MCP server

TP-Link Omada MCP server

🤖 AI-Developed Repository

Since March 2, 2026, this repository contains no human-written code.

All planning, development, and code review is performed by AI agents. Humans remain in the loop for direction, decisions, and final approval — but every line of code, every test, every commit, and every PR is the work of AI.

This is not an experiment. This is how it works now. Know more

A Model Context Protocol (MCP) server implemented in TypeScript that exposes the TP-Link Omada controller APIs to AI copilots and automation workflows. The server authenticates against a controller, lists sites, devices, and connected clients, and offers a generic tool to invoke arbitrary Omada API endpoints.

Compatibility: Tested with Omada Controller versions 5.x and 6.x

Quick Start

Using with Claude Desktop (stdio)

1. Pull the Docker image (or build it locally with npm run docker:build):

   docker pull jmtvms/tplink-omada-mcp:latest
   

2. Add the MCP server to Claude Desktop configuration. Edit your Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

3. Add the following configuration:

   {
     "mcpServers": {
       "tplink-omada": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-e", "OMADA_BASE_URL=https://your-omada-controller.local",
           "-e", "OMADA_CLIENT_ID=your-client-id",
           "-e", "OMADA_CLIENT_SECRET=your-client-secret",
           "-e", "OMADA_OMADAC_ID=your-omadac-id",
           "-e", "OMADA_SITE_ID=your-site-id",
           "-e", "OMADA_STRICT_SSL=false",
           "jmtvms/tplink-omada-mcp:latest"
         ]
       }
     }
   }
   

   Replace the environment variable values with your actual Omada controller credentials.

4. Restart Claude Desktop to load the new MCP server configuration.

5. Verify the connection by asking Claude to list your Omada sites or devices.

Using Docker Containers

CLI/stdio Container

docker run -it --rm \
  --env-file .env \
  jmtvms/tplink-omada-mcp:latest

HTTP Server Container

docker run -d \
  --env-file .env \
  -e MCP_SERVER_USE_HTTP=true \
  -e MCP_HTTP_BIND_ADDR=0.0.0.0 \
  -p 3000:3000 \
  jmtvms/tplink-omada-mcp:latest

The HTTP server will be available at http://localhost:3000/mcp.

Features

• OAuth client-credentials authentication with automatic token refresh
• Tools for retrieving sites, network devices, and connected clients
• Generic Omada API invoker for advanced automation scenarios
• Environment-driven configuration
• Per-tag Omada OpenAPI references stored under docs/openapi
• Ready-to-use devcontainer with a companion Omada controller service

Getting started

Prerequisites

• Docker (for running pre-built containers) or Node.js 24+ (for local development)
• Access to a TP-Link Omada controller (for example using the mbentley/omada-controller Docker image)

Configuration

The MCP server reads its configuration from environment variables. See .env.example for a complete reference.

Tool Category Filtering

Category Reference

Categories marked with * are reserved for upcoming phases and have no tool implementations yet. Specifying them will produce a startup warning and they will be skipped. Write tools are currently limited to the clients category.

Group aliases expand to all categories in their group:

Examples:

# Read-only access to everything
OMADA_TOOL_CATEGORIES=all:r

# Default safe subset (read only)
OMADA_TOOL_CATEGORIES=dashboard:r,client-insights:r,clients:r,devices-all:r

# Full access including write operations
OMADA_TOOL_CATEGORIES=all:rw

# Network read + client write operations
OMADA_TOOL_CATEGORIES=network-all:r,clients:rw

Omada Client Configuration

MCP Generic Server Configuration

Session IDs and authentication: When OMADA_CLIENT_ID, OMADA_CLIENT_SECRET, and OMADA_OMADAC_ID are provided (the default client-credentials mode), the server runs statelessly and treats the Mcp-Session-Id header as optional. A future OAuth-based user authentication mode will require this header again.

MCP Server HTTP Configuration

These variables are only used when MCP_SERVER_USE_HTTP=true:

Development

npm run dev

The dev mode keeps the TypeScript server running with live reload support via tsx.

Building

npm run build

Linting

npm run check

Testing

Unit tests

npm test               # run all unit tests
npm run test:watch     # watch mode
npm run test:coverage  # with coverage report

Coverage thresholds:

Integration tests (Docker)

Not implemented yet — this section documents the planned integration test strategy tracked in #57 and #58.

Integration tests will run against a real Omada Software Controller in a Docker container. They are not planned to run on every PR — they serve as a milestone release gate and a test harness for write tools.

Planned layout:

• test/docker/ (compose + snapshot/seed tooling)
• tests/integration/
• npm run test:integration

⚠️ Phase 2 write tools must only be tested against the Docker controller — never against a production controller.

Running the MCP server

npm start

The MCP server communicates over standard input and output. Integrate it with MCP-compatible clients by referencing the npm start command and providing the required environment variables.

Docker image

A container image is provided for running the MCP server:

npm run docker:build  # Build the Docker image (tag: jmtvms/tplink-omada-mcp:latest)
npm run docker:run    # Launch the container with your .env file
npm run docker:push   # Push the image to Docker Hub

You can also pull the pre-built image directly from Docker Hub:

docker pull jmtvms/tplink-omada-mcp:latest

The same image supports both stdio and HTTP transports - configure the desired mode using environment variables (e.g., set MCP_SERVER_USE_HTTP=true for HTTP mode).

Debugging with MCP Inspector

Use the MCP Inspector to interactively test tools, resources, and prompts without leaving your browser. The inspector automatically adapts to your .env configuration:

• npm run inspector — Launches the inspector based on your .env settings:

  • If MCP_SERVER_USE_HTTP=false (or unset): Runs the server in stdio mode with tsx src/index.ts for live reload debugging
  • If MCP_SERVER_USE_HTTP=true: Connects to an already-running HTTP server at the configured port/transport (start the server first with npm run dev)

• npm run inspector:build — Compiles the project first, then launches the inspector against the production build (dist/index.js) to verify release parity. Also adapts to stdio or HTTP mode based on .env.

Requirements: The inspector requires a .env file at the repository root. It will load both .env and .env.local (if present) to determine the server mode, port, transport, and path.

The MCP Inspector tool automatically binds to localhost and generates a session token for authentication (printed to the console and auto-filled in the browser URL).

Transport Protocols

The MCP server uses the Streamable HTTP transport, which implements the MCP protocol version 2025-03-26.

export MCP_SERVER_USE_HTTP=true
npm run dev

Features:

• Single endpoint for all operations (GET, POST, DELETE)
• Server-Sent Events for streaming responses
• Built-in session management with cryptographic session IDs (the server currently operates statelessly when using client credentials)

The endpoint defaults to /mcp and handles:

• GET /mcp - Establish SSE stream and initialize session
• POST /mcp - Send JSON-RPC messages
• DELETE /mcp - Terminate session

Security Considerations

DNS rebinding protection is enabled by default:

• Origin Validation: The server validates the Origin header on all incoming connections. Configure allowed origins with MCP_HTTP_ALLOWED_ORIGINS (default: 127.0.0.1, localhost). Use * to allow all origins (development only, not recommended for production).
• Network Binding: The server binds to 127.0.0.1 by default, restricting access to localhost only. Set MCP_HTTP_BIND_ADDR=0.0.0.0 to expose the server to your network (not recommended for production without additional security measures).

For more information on the MCP protocol and transports, see the Model Context Protocol documentation.

HTTP transport usage

Start the HTTP transport with:

# Start with HTTP enabled
export MCP_SERVER_USE_HTTP=true
npm run dev    # live reload during development
npm run start  # run the compiled output

By default, the server listens on 127.0.0.1:3000 and exposes the MCP endpoint at /mcp with a health check on /healthz. Configure the bind address, port, and path using the optional MCP_HTTP_* environment variables documented in .env.example. The npm run docker:run:http helper wraps the HTTP image and publishes the port automatically.

Using ngrok

To share the local server with remote tooling, you can use ngrok to expose the HTTP server publicly.

Option 1: Built-in ngrok support (recommended)

Set the following environment variables:

export MCP_HTTP_NGROK_ENABLED=true
export MCP_HTTP_NGROK_AUTH_TOKEN=your-ngrok-auth-token
npm run dev

The server will automatically establish an ngrok tunnel and log the public URL.

Option 2: Manual ngrok setup

Run ngrok in a separate terminal after starting the server:

ngrok http 3000

This forwards a public HTTPS URL to http://localhost:3000 and prints the tunnel address in the console.

In client-credentials mode the server already treats Mcp-Session-Id as optional; if the header is removed in transit, requests will still succeed.

Tools

Site & Client

Device

Network

Firewall & ACL

Firewall Traffic & QoS

Firewall IDS / IPS

Security & Threat Management

Dashboard / Monitor

Insight

VPN

Profiles

Logs

Controller

Maintenance

Account Users

Account Cloud

Schedules

Supported Omada API Operations

Devcontainer support

The repository includes a ready-to-use devcontainer configuration with a dedicated Omada controller sidecar for local development and testing. See .devcontainer/README.md for details.

License

This project is licensed under the MIT License.