MiguelTVMS/tplink-omada-mcp

TP-Link Omada MCP server

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.

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 (stream transport) or http://localhost:3000/sse (SSE transport).

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.

Omada Client Configuration

MCP Generic Server Configuration

MCP Server HTTP Configuration

These variables are only used when MCP_SERVER_USE_HTTP=true:

Create a .env file (ignored by git) or export the variables before launching the server.

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

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).

Transport Protocols

The MCP server supports two HTTP transport protocols:

Streamable HTTP (Default)

The Streamable HTTP transport implements the MCP protocol version 2025-03-26. This is the recommended transport for new integrations.

# Set transport to stream (default)
export MCP_SERVER_USE_HTTP=true
export MCP_HTTP_TRANSPORT=stream
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
• Support for stateless mode when needed

The Streamable HTTP endpoint defaults to /mcp and handles:

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

HTTP with SSE (Legacy)

The HTTP+SSE transport implements the MCP protocol version 2024-11-05. This transport is provided for backward compatibility with older MCP clients.

# Set transport to sse for legacy clients
export MCP_SERVER_USE_HTTP=true
export MCP_HTTP_TRANSPORT=sse
npm run dev

Features:

• Separate endpoints for SSE stream and POST messages
• Compatible with older MCP client implementations

The SSE transport uses two endpoints:

• GET /sse - Establish SSE connection
• POST /messages - Send JSON-RPC messages

Security Considerations

Both transports implement DNS rebinding protection:

• 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 (for stream transport) or /sse (for SSE transport) 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 (works with both transports)

To share the local server with remote tooling, you can use ngrok to expose the HTTP server publicly. This works with both stream and SSE transports.

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.

If an intermediary strips the Mcp-Session-Id header, set MCP_SERVER_STATEFUL=false to disable server-managed sessions and allow stateless requests.

Tools

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 for details.

License

This project is licensed under the .