MikroTik MCP / Docs / Installation

Installation

Several ways in: the MCP Registry one-liner (recommended), a Docker container, or a manual Python install — plus HTTP transports for remote agents. Pick whichever matches your environment; all of them speak the same MCP protocol.

PRE-FLIGHT

You'll need a RouterOS device with SSH/API access enabled, a username with write policy, and (ideally) SSH key auth. Default SSH port is 22.

Prerequisites

Python 3.8+ — only if you're not running via Docker.
MikroTik RouterOS device with API/SSH access enabled.
Network reachability from your machine to the router's SSH port.
An MCP-capable client — Claude Desktop, MCP Inspector, or any tool that speaks MCP.

MCP Registry (recommended)

MikroTik MCP is listed on the MCP Registry — a community catalog of MCP servers. Registry-aware clients (Claude Desktop, VS Code, Cursor) can install it in one command without hand-editing config files.

# One-line install for registry-aware clients

$ claude mcp add io.github.jeff-nasseri/mikrotik-mcp

The client fetches the server metadata from the registry, installs mcp-server-mikrotik from PyPI, and prompts you for the required environment variables — MIKROTIK_HOST, MIKROTIK_USERNAME, and MIKROTIK_PASSWORD.

NOTE

If your client does not support registry-based install, use the Docker or manual methods below — both pull the same mcp-server-mikrotik package.

Docker

The fastest path when you'd rather not touch a Python toolchain. The image bundles Python, the server, and all dependencies — you just provide credentials.

1 · Clone & build

$ git clone https://github.com/jeff-nasseri/mikrotik-mcp.git
$ cd mikrotik-mcp
$ docker build -t mikrotik-mcp .

Run with stdio (IDE / desktop client)

stdio transport is what Claude Desktop, Cursor, and most IDE integrations expect. The container reads MCP messages from stdin and writes responses to stdout — short-lived, one process per client.

~/.cursor/mcp.json or claude_desktop_config.json

{
  "mcpServers": {
    "mikrotik-mcp-server": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "MIKROTIK_HOST=192.168.88.1",
        "-e", "MIKROTIK_USERNAME=sshuser",
        "-e", "MIKROTIK_PASSWORD=your_password",
        "-e", "MIKROTIK_PORT=22",
        "mikrotik-mcp"
      ]
    }
  }
}

Run with SSE or streamable HTTP

For remote agents, REST consumers, and anything that isn't on the same machine. Exposes a long-running HTTP server with a /health probe.

# SSE on port 8000

$ docker run --rm -p 8000:8000 \
    -e MIKROTIK_HOST=192.168.88.1 \
    -e MIKROTIK_USERNAME=sshuser \
    -e MIKROTIK_PASSWORD=your_password \
    -e MIKROTIK_MCP__TRANSPORT=sse \
    mikrotik-mcp

# Available at:
#   SSE             →  http://localhost:8000/sse
#   Streamable HTTP →  http://localhost:8000/mcp
#   Health          →  GET  http://localhost:8000/health

Environment variables

Variable	Description	Default
`MIKROTIK_HOST`	Device IP / hostname	`192.168.88.1`
`MIKROTIK_USERNAME`	SSH username	`admin`
`MIKROTIK_PASSWORD`	SSH password	(empty)
`MIKROTIK_PORT`	SSH port	`22`
`MIKROTIK_MCP__TRANSPORT`	Transport — `stdio` · `sse` · `streamable-http`	`stdio`
`MIKROTIK_MCP__HOST`	HTTP listen address	`0.0.0.0`
`MIKROTIK_MCP__PORT`	HTTP listen port	`8000`

Manual install

If you prefer to run from a Python venv — useful for development and debugging.

# Source install

# Clone the repository
$ git clone https://github.com/jeff-nasseri/mikrotik-mcp.git
$ cd mikrotik-mcp

# Create & activate virtual environment
$ python -m venv .venv
$ source .venv/bin/activate    # Windows: .venv\Scripts\activate

# Install in editable mode
$ pip install -e .

# Run the server (stdio, default)
$ mcp-server-mikrotik

# Or with SSE / streamable HTTP transport
$ mcp-server-mikrotik --mcp.transport sse
$ mcp-server-mikrotik --mcp.transport streamable-http

CLI options

Flag	Description	Default
`--host`	MikroTik device IP / hostname	from config
`--username`	SSH username	from config
`--password`	SSH password	from config
`--key-filename`	SSH key file (preferred over password)	from config
`--port`	SSH port	`22`
`--mcp.transport`	`stdio` · `sse` · `streamable-http`	`stdio`
`--mcp.host`	HTTP listen address	`0.0.0.0`
`--mcp.port`	HTTP listen port	`8000`

TIP

Prefer SSH keys over passwords for production. Pass --key-filename ~/.ssh/mikrotik_ed25519 and register the matching public key under /user ssh-keys on the device.

HTTP-based transports (sse, streamable-http) expose a GET /health endpoint for health checks. This endpoint is not available in stdio mode.

Testing the install

Once the server is up, the quickest sanity check is the MCP Inspector — it speaks MCP, lists every tool, and lets you invoke them by hand.

# Inspector against a fresh install

$ npx @modelcontextprotocol/inspector \
    uvx mcp-server-mikrotik \
    --host 192.168.88.1 \
    --username admin \
    --password "<PASSWORD>" \
    --port 22

A browser tab opens with the tool catalog. Try mikrotik_list_vlan_interfaces with empty arguments — if you get back a JSON list, you're in. Contributors can also run the project's pytest suite against a RouterOS container; see testing.md.

Context length optimization

MikroTik MCP ships 169 tools. At full verbosity the tool schema can occupy ≈ 54,000 tokens — more than the entire context window of many local LLMs (LM Studio, Ollama, and similar).

To keep that manageable, every tool carries a short title annotation (per the MCP tool-annotations spec) plus a trimmed one-line description. The function signature already carries full type information, so the description only needs to convey what the tool does. This cuts the description token budget by roughly 75% — bringing the schema for a 64k-token model from ≈ 54k → ≈ 48k tokens and leaving real room for the conversation.

FURTHER

Need only a subset of tools (say, just DNS and WireGuard)? Comment out the unused scope imports in src/mcp_mikrotik/app.py to drop those categories entirely — the dropped tools never reach the schema at all.