Skip to main content
Glama
README.md
# gns3-lab-mcp

An MCP server that lets an AI agent build real network labs in
[GNS3](https://www.gns3.com/): create a project, add routers, switches, and
hosts from the templates your GNS3 server already has, cable their ports
together, start them, and hand back a Mermaid diagram of the result. It wraps
the GNS3 controller's REST API through
[`gns3fy`](https://github.com/davidban77/gns3fy), turns every response into
clean JSON (or a friendly `Error: ...` string), and ships an
[agent skill](SKILL.md) that teaches the complete lab-design workflow.

The distribution is named **`gns3-lab-mcp`** on PyPI (not yet published —
install from source below); the import package is `gns3_mcp`.

<!-- Demo placeholder: record a session building the two-router OSPF lab from
     SKILL.md and drop the GIF here. -->
> **Demo:** _GIF placeholder — an agent creating the two-router OSPF lab from
> [SKILL.md](SKILL.md), then rendering the diagram below._

```mermaid
graph TD
    n0["R1"]
    n1["R2"]
    n0 --- n1
```

## Requirements

- GNS3 2.2 or newer, with its controller reachable over HTTP
  (default `http://localhost:3080`). `GNS3_BASE_URL` may include or omit a
  trailing `/v2`.
- Node templates with their images installed on that controller — the server
  can list and add nodes, but it cannot install images.
- No local Python install is needed: `uvx` fetches and runs the package.

## Install

```bash
uvx gns3-lab-mcp
```

The console script starts the MCP server on stdio. Point it at a GNS3
controller other than the default with:

```bash
GNS3_BASE_URL=http://192.168.1.10:3080 uvx gns3-lab-mcp
```

## Client configuration

### OpenCode

Add this to `opencode.json` (project or global):

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gns3": {
      "type": "local",
      "command": ["uvx", "gns3-lab-mcp"],
      "enabled": true,
      "environment": {
        "GNS3_BASE_URL": "http://localhost:3080"
      }
    }
  }
}
```

### Claude Code

Add this to `.mcp.json` in the project root, or use `claude mcp add`:

```json
{
  "mcpServers": {
    "gns3": {
      "command": "uvx",
      "args": ["gns3-lab-mcp"],
      "env": {
        "GNS3_BASE_URL": "http://localhost:3080"
      }
    }
  }
}
```

## Tools

Every tool returns text. Mutating tools return the created or changed object as
indented JSON; failures come back as a string starting with `Error:` rather
than raising.

Error handling is deliberately split: failures to reach the controller say
`cannot reach GNS3 server at <url>` (with the `is gns3server running?` hint on
`gns3_version`), a request that hangs for 30 seconds says `timed out contacting
GNS3 server at <url>`, and a controller that answers with an HTTP error returns
GNS3's own message — for example `node name already used in this project`,
without the status-code prefix gns3fy adds.

| Tool | Arguments | Returns |
| --- | --- | --- |
| `ping` | — | `pong` when the MCP server is alive |
| `gns3_version` | — | GNS3 server version information |
| `list_projects` | — | JSON list of `{project_id, name, status}` |
| `create_project` | `name` | JSON `{project_id, name, status}` |
| `open_project` | `project_id` | JSON `{project_id, status: "opened"}`; already-open projects are left alone |
| `list_templates` | — | JSON list of `{template_id, name, category}` |
| `list_nodes` | `project_id` | JSON list of `{node_id, name, status, node_type}` |
| `add_node` | `project_id`, `template_id`, `name` | JSON node `{node_id, name, status, node_type}` |
| `start_node` | `project_id`, `node_id` | JSON `{project_id, node_id, status: "started"}` |
| `stop_node` | `project_id`, `node_id` | JSON `{project_id, node_id, status: "stopped"}` |
| `add_link` | `project_id`, `node_a_id`, `adapter_a`, `port_a`, `node_b_id`, `adapter_b`, `port_b` | JSON link `{link_id, node_ids}` |
| `list_links` | `project_id` | JSON list of `{link_id, node_ids}` |
| `draw_topology` | `project_id` | Mermaid `graph TD` diagram as text |

Notes:

- `add_node` has no position arguments: nodes are created at canvas position
  `(0, 0)` and overlap until moved in the GNS3 GUI. `draw_topology` is
  unaffected — it draws from nodes and links, not coordinates.
- Link ports are zero-based (`adapter_a=0, port_a=0` is the first port on the
  first adapter). GNS3 rejects a port that is already in use.
- The server does not configure devices, open consoles, delete objects, or take
  snapshots.

## Agent skill

[`SKILL.md`](SKILL.md) is an Agent-Skills-standard skill named
`gns3-lab-designer`. It covers template discovery, the build workflow, naming
conventions (`R1`, `R2`, `SW1`), a worked two-router OSPF example, and
troubleshooting. Install it by copying it into your agent's skills directory,
for example:

```bash
mkdir -p ~/.claude/skills/gns3-lab-designer
cp SKILL.md ~/.claude/skills/gns3-lab-designer/SKILL.md
```

## Development

```bash
uv sync
uv run pytest tests/ -v
```

## License

[MIT](LICENSE)