gns3-lab-mcp
by FMB237
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)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues