LANForge MCP

Universal Model Context Protocol server for controlling and observing Candela LANforge from MCP-compatible AI clients.

LANForge MCP gives an AI a compact operator interface while preserving access to the full LANforge surface:

• Any JSON GET table through query and live endpoint discovery

• Any CLI-JSON command through run_command or raw_cli

• LANforge scripts discovered from their real argparse schemas

• Wi-Fi stations, L3/L4 traffic, monitoring, events, alerts, attenuators, reports, diagnostics, and reusable workflows

• Multiple LANforge systems from one server

• stdio for desktop AI clients and Streamable HTTP for shared deployments

• Linux, macOS, Windows, Docker, and LANforge-local deployment when Python 3.10+ is available

The design deliberately uses about 40 understandable tools plus dynamic gateways instead of exposing 600+ nearly identical MCP tools.

Safety first

First launch is read-only and remote shell access is disabled. Full LANforge control is available only when the operator opts in:

safety:
  read_only: false
  dry_run: false
  require_confirmation: true
  allow_shell: true
  allow_runtime_mode_changes: false

Destructive commands still require confirm=true. Every mutation is audited with common credentials recursively redacted. Runtime safety changes are locked unless an administrator explicitly enables them.

Related MCP server: testing-mcp

Install

Python 3.10 or newer is required.

Linux / macOS

git clone https://github.com/AarifCandela/LANForge-MCP.git
cd LANForge-MCP
./scripts/install.sh
. .venv/bin/activate
lanforge-mcp version

Windows PowerShell

git clone https://github.com/AarifCandela/LANForge-MCP.git
Set-Location LANForge-MCP
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1
.\.venv\Scripts\Activate.ps1
lanforge-mcp version

Release wheel

Download the wheel from the latest GitHub release, then:

python -m venv .venv
# activate the venv, then:
python -m pip install lanforge_mcp-1.0.0-py3-none-any.whl

Connect to LANforge

Copy the example and edit the host:

cp examples/config.yaml config.yaml
lanforge-mcp check --config config.yaml

The LANforge GUI JSON API is normally http://LANFORGE_IP:8080. SSH is optional and is needed only for remote scripts and shell_command.

Connect an AI client (stdio)

Use the absolute executable and config paths for maximum portability:

{
  "mcpServers": {
    "lanforge": {
      "command": "/absolute/path/LANForge-MCP/.venv/bin/lanforge-mcp",
      "args": ["serve", "--config", "/absolute/path/LANForge-MCP/config.yaml"]
    }
  }
}

On Windows, command is typically C:\\path\\LANForge-MCP\\.venv\\Scripts\\lanforge-mcp.exe.

See docs/clients.md for Claude Desktop/Code, Cursor, VS Code, Cline, Continue, Hermes, and generic clients.

Remote HTTP deployment

Non-loopback HTTP requires a bearer token unless the operator explicitly overrides the guard:

export LANFORGE_MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
lanforge-mcp serve --transport http --bind 0.0.0.0 --port 8231 --config config.yaml

Clients connect to http://SERVER:8231/mcp and send the configured bearer token in the Authorization header. Terminate TLS at a trusted reverse proxy for traffic outside a private lab network.

Docker:

export LANFORGE_HOST=192.168.1.50
export LANFORGE_MCP_AUTH_TOKEN="replace-with-a-long-random-token"
docker compose up --build -d

See docs/deployment.md.

Universal LANforge access model

Unknown commands are forwarded to the connected GUI, so newer LANforge features do not require an MCP release. Offline catalogs improve discoverability but the installed LANforge GUI remains authoritative.

Validate the server

.venv/bin/pytest
.venv/bin/ruff check src tests tools
.venv/bin/mypy src
.venv/bin/fastmcp list --command '.venv/bin/lanforge-mcp serve --config config.yaml' --json

Use read-only mode for the first live connection. Only perform mutating hardware tests on an authorized lab system.

Documentation

• User guide

• AI client setup

• Deployment guide

• Tool reference

• Architecture

• Security

• Troubleshooting

• FAQ

• Developer guide

License and trademarks

MIT licensed. LANforge is a product and trademark of Candela Technologies. This repository is an independent MCP integration and is not an official Candela support channel.