tplinkctl

Autonomous agent-ready CLI and stdio JSON-RPC MCP server for local TP-Link router management.

tplinkctl turns stateful, slow, and browser-dependent router admin interfaces into a high-speed, local-first API interface designed for humans, shell scripts, and autonomous AI coding agents (Hermes, Claude Code, Cursor, Codex, OpenClaw).

Key Highlights

• 🛡️ Autonomous Mutation Safety: Plan-before-execute via --plan / --dry-run, mandatory --yes confirmations on destructive actions, noise-filtered state snapshot diffing (state diff), and rollback contracts.
• 🤖 Agent-First Discovery: Full CLI Spec v0.2 compliance via tplinkctl schema, structured semantic exit codes, JSON error envelopes on stderr, and built-in capabilities, AGENTS.md, and llms.txt.
• ⚡ Dual Transport (CLI + MCP): 50+ CLI subcommands paired with 30 stdio JSON-RPC MCP tools in tplinkctl-mcp with zero heavy SDK dependencies.
• 🔒 Granular Policy Profiles: 4 security tiers (read-only, device-admin, network-admin, dangerous) to safely constrain autonomous agents in long-running sessions.
• 📡 Deep Hardware Coverage: 55+ reverse-engineered endpoints covering Wi-Fi 7 (OFDMA, TWT, DFS, Smart Connect), EasyMesh, WireGuard VPN, QoS bandwidth limits, NAT ALG/DMZ/UPnP, IPTV/VLAN, USB storage sharing, and power eco schedules.

Quick Start

1. Install

# From PyPI (published as tplink-admin-cli — `tplinkctl` is the GitHub project name, not the PyPI name)
pip install tplink-admin-cli

# From source (or via uv / pip)
git clone https://github.com/JithendraNara/tplinkctl.git
cd tplinkctl
python3 -m venv .venv
.venv/bin/pip install -e .

2. Configure

Set non-secret router defaults and export your password in the environment:

tplinkctl config set --host http://192.168.0.1 --username admin --client sg
export TPLINK_PASSWORD="your-local-router-password"

3. Inspect

# Verify connection & readiness
tplinkctl doctor
tplinkctl --json status

# Introspect machine-readable CLI contract
tplinkctl schema

Command Surface & Tool Matrix

Agent Safety & Policy Profiles

tplinkctl provides four security profile envelopes to restrict agent execution permissions:

Set policy profiles via CLI flag or environment variable:

# Per-command profile
tplinkctl --json --profile read-only status
tplinkctl --json --profile device-admin device block Pixel --dry-run

# Session-wide profile
export TPLINK_PROFILE=device-admin

The Plan → Execute → Verify → Audit Loop

Autonomous agents should follow this standard mutation lifecycle:

# 1. Plan the change (dry-run preview with rollback instructions)
tplinkctl --json --reason "pause guest device" --no-input device block Pixel --plan --enforce

# 2. Execute with explicit confirmation
tplinkctl --json --reason "pause guest device" --no-input device block Pixel --yes --enforce

# 3. Verify state diff (rate/timestamp noise is filtered automatically)
tplinkctl --json --no-input state save --name after-block
tplinkctl --json state diff --before before-block --after after-block

# 4. Review audit trail
tplinkctl --json events --tail 5

MCP Server Integration

tplinkctl-mcp exposes 30 router tools over standard JSON-RPC stdio (no MCP SDK / FastMCP dependency — see src/tplink_admin/mcp.py). Mutating MCP tools require confirm=true in tool arguments.

Add tplinkctl-mcp to your agent configuration:

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "tplink": {
      "command": "tplinkctl-mcp",
      "env": {
        "TPLINK_HOST": "http://192.168.0.1",
        "TPLINK_USERNAME": "admin",
        "TPLINK_PASSWORD": "your-router-password",
        "TPLINK_CLIENT": "sg",
        "TPLINK_MCP_PROFILE": "device-admin"
      }
    }
  }
}

Hermes Agent / Cursor / OpenClaw

mcp_servers:
  tplink:
    command: "tplinkctl-mcp"
    env:
      TPLINK_HOST: "http://192.168.0.1"
      TPLINK_PASSWORD: "${TPLINK_PASSWORD}"
      TPLINK_MCP_PROFILE: "device-admin"

The CLI Spec (clispec v0.2) & Exit Codes

tplinkctl fully implements The CLI Spec v0.2:

Introspection

Agents can discover all commands, arguments, types, defaults, and mutation contracts offline without executing network calls:

# Entire command tree
tplinkctl schema

# Subtree narrowing (token-efficient)
tplinkctl schema device
tplinkctl schema wifi-config

Semantic Exit Codes

Failures write a single-line JSON error envelope as the last line of stderr:

{"error": {"kind": "confirmation_required", "message": "Refusing to block without --yes.", "hint": "Re-run with --plan or --dry-run first, then add --yes."}}

Router & Hardware Compatibility

tplinkctl is built on tplinkrouterc6u (>=5.30.0) and includes an active payload normalizer for TP-Link's SG authentication protocol.

Development & Verification

# Run unit test suite (86 tests)
make test

# Run offline smoke suite
make smoke

# Run agent workflow demo
make demo

# Deep health verification against live router
tplinkctl --json --no-input doctor --deep

Documentation Links

• AGENTS.md — Operational instructions, discovery guidelines, and playbooks for AI agents.
• llms.txt — LLM-optimized summary and context index.
• docs/ENDPOINTS.md — Complete reverse-engineered endpoint and payload reference.
• docs/INSTALL_AGENT.md — Detailed agent integration and MCP configuration guide.
• examples/agent-runbook.md — End-to-end agent operational runbook.
• CHANGELOG.md — Version history and release notes.

License

GNU GPLv3 or later © Jithendra Nara