# 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:

```yaml
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.

## Install

Python 3.10 or newer is required.

### Linux / macOS

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

### Windows PowerShell

```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:

```bash
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:

```bash
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:

```json
{
  "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](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:

```bash
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:

```bash
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](docs/deployment.md).

## Universal LANforge access model

| Capability | MCP tools |
|---|---|
| Systems and health | `connect`, `disconnect`, `systems`, `health_check` |
| Every read table | `list_endpoints`, `query`, `inventory` |
| Every CLI command | `list_commands`, `command_help`, `run_command`, `raw_cli` |
| LANforge OS (optional) | `shell_command` |
| Wi-Fi stations | `create_stations`, `station_status`, `diagnose_stations`, `remove_ports` |
| Traffic | L3/L4 create/start/stop/remove, stats and diagnosis |
| Observability | `monitor`, `events`, `alerts`, event analysis and comparisons |
| Automation suites | script discovery/schema/run/status/output/cancel |
| Campaigns | workflow templates and arbitrary declarative workflows |
| Evidence | Markdown, standalone HTML, and JSON reports |

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

```bash
.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](docs/user-guide.md)
- [AI client setup](docs/clients.md)
- [Deployment guide](docs/deployment.md)
- [Tool reference](docs/tools.md)
- [Architecture](docs/architecture.md)
- [Security](docs/security.md)
- [Troubleshooting](docs/troubleshooting.md)
- [FAQ](docs/faq.md)
- [Developer guide](docs/developer-guide.md)

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