tplink-mcp

Overview

TP-Link Router MCP Server is a production-ready implementation of the Model Context Protocol (MCP 2.x) that grants autonomous AI agents safe, structured access to TP-Link cellular gateways and broadband routers. Supported agent frameworks include Google Antigravity, Claude Desktop, Cursor, and OpenAI Codex.

Conceived during network tuning experiments on Hutch 4G LTE unlimited connections in Malabe, Sri Lanka (near the SLIIT Campus), the server allows AI models to independently audit link telemetry, optimize radio bands, and resolve cellular bufferbloat while guaranteeing zero disruption to concurrent sessions or unauthorized networks.

To satisfy the strict single-administrator concurrency constraint enforced by TP-Link firmware, the server encapsulates every tool invocation within an atomic SafeSession context manager that authenticates, executes the request, and logs out immediately. Potentially disruptive tool calls enforce explicit confirmation arguments to prevent AI models from severing active connectivity.

Related MCP server: ax11000-mcp

Architecture & Modes

The server provides flexible deployment models across standard process transports, containerized runtimes, and package managers.

sequenceDiagram
    autonumber
    participant Agent as AI Copilot (Antigravity / Claude)
    participant MCP as TP-Link MCP Server
    participant Guard as Network Profile Guard
    participant Session as SafeSession Manager
    participant Router as TP-Link Gateway (192.168.1.1)

    Agent->>MCP: Call Tool (e.g. router_get_rf_signal)
    MCP->>Guard: Verify Gateway IP and SSID safety
    Guard-->>MCP: Safety Verified
    MCP->>Session: Acquire atomic session lock
    Session->>Router: Authenticate (RSA-1024 / AES-128)
    Router-->>Session: Authenticated Token
    Session->>Router: Dispatch TR-064 Query
    Router-->>Session: Telemetry Payload
    Session->>Router: Immediate Logout (Release Session)
    Session-->>MCP: Sanitized Data
    MCP-->>Agent: Return Tool Result JSON

Project Structure

.
├── tplink_mcp/                 # MCP server and tool registry
│   ├── server.py               # MCP 2.x protocol entrypoint and JSON-RPC router
│   ├── tools/                  # 18 typed MCP tool definitions
│   └── core/                   # Session leasing, network safety, and crypto
├── bin/                        # Node.js binary wrapper for npx distribution
├── Dockerfile                  # Container definition for GHCR deployment
├── smithery.yaml               # Smithery marketplace manifest
├── tests/                      # Automated test suite (63 unit tests)
├── package.json                # npm wrapper configuration
├── pyproject.toml              # Python build and dependency manifest
└── README.md

Installation

Claude Desktop Configuration

Add the server entry to your claude_desktop_config.json:

{
  "mcpServers": {
    "tplink-mcp": {
      "command": "npx",
      "args": ["-y", "tplink-mcp"],
      "env": {
        "TPLINK_ROUTER_IP": "http://192.168.1.1",
        "TPLINK_PASSWORD": "your_router_password"
      }
    }
  }
}

Google Antigravity & Cursor Configuration

Configure directly using Python stdio transport:

{
  "mcpServers": {
    "tplink-mcp": {
      "command": "python3",
      "args": ["-m", "tplink_mcp.server"],
      "env": {
        "TPLINK_ROUTER_IP": "http://192.168.1.1",
        "TPLINK_PASSWORD": "your_router_password"
      }
    }
  }
}

Docker Container (Zero-Install)

docker run -i --rm --network host \
  -e TPLINK_ROUTER_IP="http://192.168.1.1" \
  -e TPLINK_PASSWORD="your_router_password" \
  ghcr.io/dulithdivisekara/tplink-mcp:latest

Usage

Core Tools Catalog

The server exposes 18 typed MCP tools categorized by operational risk:

Session Logging & Inspection

The MCP specification mandates clean stdout for JSON-RPC message frames. All server diagnostic logs are routed strictly to stderr or designated files:

• Audit Log Path: ~/.config/tplink-router/mcp.log

• Stream Live Logs:

  tail -f ~/.config/tplink-router/mcp.log

Verification Tests

Run the automated test suite verifying tool schemas, validation handlers, and mock gateway responses:

python3 -m unittest discover tests

Ran 63 tests in 19.603s

OK

Security & Privacy

• SafeSession Isolation: Eliminates lockout errors on the web administrative portal by guaranteeing immediate atomic session teardown.

• Disconnection Guardrails: Destructive commands enforce confirm=True to prevent recursive disconnection where an AI agent severs its own connection.

• Network Profile Validator: Halts execution if the client is connected to university campus Wi-Fi or unauthorized networks.

• Credential Segregation: Credentials are supplied via environment variables or protected configuration files with owner-only (0600) POSIX permissions.

License

This project is licensed under the MIT License. Author: Dulith Divisekara.