MikroTik MCP Server

MCP server that lets Claude Code manage one or multiple MikroTik routers through the RouterOS v7 REST API.

Claude discovers endpoints via a built-in search index (689 consolidated resources from the RouterOS 7.16 OpenAPI spec) and executes requests against your routers — all through natural language.

Quick start

One-line installer

The interactive installer checks prerequisites, tests connectivity to your router, and registers the MCP server in Claude Code:

curl -fsSL https://raw.githubusercontent.com/serengon/mikrotik-mcp-server/main/install.sh | bash

Or if you have the repo cloned:

bash install.sh

It supports both single-router and multi-router setups. Just follow the prompts.

Manual setup (single router)

You need Claude Code and a RouterOS v7 device (physical or Docker).

1. Install uv (Python package runner)

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Add the MCP server to Claude Code

claude mcp add mikrotik \
  -e ROUTEROS_URL=http://192.168.1.1 \
  -e ROUTEROS_USER=admin \
  -e ROUTEROS_PASSWORD= \
  -e ROUTEROS_VERIFY_SSL=false \
  -- uvx --from "git+https://github.com/serengon/mikrotik-mcp-server.git" mikrotik-mcp

3. Start a test router (optional)

If you don't have a physical MikroTik, run one in Docker (requires KVM — check with ls /dev/kvm):

docker run -d --name routeros --cap-add NET_ADMIN \
  --device /dev/net/tun --device /dev/kvm \
  -p 8080:80 -p 8443:443 -p 2222:22 \
  evilfreelancer/docker-routeros:7.16

Wait ~30 seconds for it to boot, then verify:

curl -s -u admin: http://localhost:8080/rest/system/resource | head -c 200

Default credentials: admin with no password. Use ROUTEROS_URL=http://localhost:8080.

4. Try it

claude

Type /mcp — you should see mikrotik connected with 3 tools. Then ask:

• "What interfaces does the router have?"
• "Show me the IP addresses"
• "What's the router's uptime?"
• "List firewall filter rules"
• "Add a static route to 10.0.0.0/8 via 192.168.1.254"

That's it. No clone, no venv, no config files.

Multi-router setup

To manage multiple routers from a single Claude Code session, create a routers.json file:

{
  "routers": {
    "edge-gw":   {"url": "http://192.168.1.1",  "user": "admin", "password": "", "verify_ssl": false},
    "core-sw":   {"url": "http://192.168.1.2",  "user": "admin", "password": "", "verify_ssl": false},
    "fw-01":     {"url": "http://192.168.1.3",  "user": "admin", "password": "", "verify_ssl": false},
    "wifi-ctrl": {"url": "http://192.168.1.4",  "user": "admin", "password": "", "verify_ssl": false}
  }
}

Then point the MCP server to it:

claude mcp add mikrotik \
  -e ROUTEROS_CONFIG=/path/to/routers.json \
  -- uvx --from "git+https://github.com/serengon/mikrotik-mcp-server.git" mikrotik-mcp

With multiple routers configured, use list_routers to see available devices and specify the target with the router parameter:

• "List all routers"
• "Show interfaces on edge-gw"
• "What firewall rules does fw-01 have?"
• "Show OSPF neighbors on all routers"

Tip: For auditing, create a read-only user on each router and use those credentials in routers.json. Add routers.json to .gitignore — it contains passwords.

How it works

Claude uses three tools to interact with routers:

Plus one resource (router://api-groups) that provides an overview of all API groups.

Configuration resolution order

1. ROUTEROS_CONFIG env var → path to a routers.json file
2. routers.json in the current working directory
3. Single-router fallback using ROUTEROS_URL / ROUTEROS_USER / ROUTEROS_PASSWORD env vars

Credential storage

Passwords are stored in your OS keyring (GNOME Keyring, macOS Keychain, or Windows Credential Store) so they never need to live in plain text on disk.

The install wizard stores passwords in the keyring automatically. Password resolution priority:

1. OS keyring (most secure)
2. routers.json file
3. Environment variables

If the keyring is unavailable, the server falls back to JSON/env vars silently.

Tip: You can remove passwords from routers.json entirely once they're in the keyring. The server will find them automatically.

Configuration reference

Connecting to a real router

1. Enable the REST API: /ip/service set www disabled=no (HTTP) or www-ssl disabled=no (HTTPS)
2. For read-only access, create a dedicated user: /user add name=mcp-audit group=read
3. For HTTPS with a custom CA, set ROUTEROS_VERIFY_SSL=true and ROUTEROS_CA_CERT=/path/to/ca.pem

The REST API requires RouterOS v7.1+.

Development setup

git clone https://github.com/serengon/mikrotik-mcp-server.git
cd mikrotik-mcp-server
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

The project includes a .mcp.json that points to the local venv, so Claude Code picks it up automatically when working from the repo. Export the env vars first:

cp .env.example .env
# edit .env with your values, then:
set -a && source .env && set +a
claude

Running tests

# Unit tests (no router needed)
.venv/bin/pytest -x -v --ignore=tests/test_integration.py

# Integration tests (requires Docker CHR running)
docker compose -f docker/docker-compose.yml up -d
.venv/bin/pytest -x -v -m integration

# Lint
.venv/bin/ruff check src/ tests/

Troubleshooting

MCP server not connecting

• Check reachability: curl -u admin: http://<router-ip>/rest/system/resource
• For Docker: wait 30s after start, check with docker logs routeros

"Multiple routers configured" error

• You have more than one router in routers.json — specify which one: "show interfaces on edge-gw"

"RouterOS error 401"

• Wrong credentials — check ROUTEROS_USER and ROUTEROS_PASSWORD

"RouterOS error 500"

• Often a permissions issue (RouterOS returns 500 instead of 403). Check user group on the router.

Project structure

src/mikrotik_mcp/
  server.py            # FastMCP entry point (tools + resource registration)
  client.py            # RouterOSClient (httpx wrapper with quirks handling)
  router_registry.py   # RouterRegistry (multi-router client management)
  api_index.py         # OAS2 keyword search index (689 consolidated resources)
  types.py             # Pydantic models and error hierarchy
  config.py            # Configuration from env vars or routers.json
  tools/
    api_tools.py       # search_api + routeros_request + list_routers
  data/
    routeros-7.16-oas2.json  # OpenAPI 2.0 spec (4607 paths)
docker/                # Docker CHR for single-router testing
gns3/                  # GNS3 enterprise rack scripts (see below)
tests/
docs/
  adr/                 # Architecture Decision Records

Lab testing with GNS3 (optional)

The multi-router features were validated against a simulated enterprise rack running 4 MikroTik CHR instances in GNS3/QEMU. The gns3/ directory contains the scripts used to set it up.

What was tested end-to-end:

If you want to reproduce the lab:

# On a Linux machine with GNS3 + QEMU + KVM:
bash gns3/start_rack.sh      # start the 4-router topology
bash gns3/reset_rack.sh      # restore baseline snapshot before each test

See gns3/ for full setup details.

License

MIT