Skip to main content

MikroTik MCP Server

FastMCP server that exposes MikroTik RouterOS REST API as MCP tools

Python RouterOS FastMCP License

Overview • Get Started • Configuration • MCP Client Setup • Troubleshooting

Manage MikroTik devices from any MCP-compatible client (Claude Code, Claude Desktop, OpenCode, or custom MCP clients) using a single server package.

Overview

This server wraps RouterOS REST endpoints (/rest/...) and exposes them as typed MCP tools.

  • Built with FastMCP + async httpx
  • Pydantic validation for inputs and settings
  • stdio, sse, and streamable-http transport modes
  • Single connection manager shared through MCP lifespan

Get Started

Prerequisites

  • Python 3.11+
  • uv (recommended) or any PEP 517 installer
  • MikroTik RouterOS v7.1+ with REST API reachable

Install

Run without installing (recommended):

uvx mikrotik-rest-mcp

Or with Nix (no Python required):

nix run github:alizdavoodi/mikrotik-rest-mcp

Install into current environment:

uv pip install mikrotik-rest-mcp

From source (contributors):

uv sync --dev

If you prefer Nix for development:

nix develop

Run

export MIKROTIK_HOST=192.168.88.1
export MIKROTIK_USERNAME=admin
export MIKROTIK_PASSWORD=yourpassword
export MIKROTIK_PORT=80

# with uv
uvx mikrotik-rest-mcp

# with nix
nix run github:alizdavoodi/mikrotik-rest-mcp

Test with MCP Inspector:

npx @modelcontextprotocol/inspector uvx mikrotik-rest-mcp

Configuration

All settings are read from process environment variables.

Variable Description Default
MIKROTIK_HOST Router IP or hostname (required)
MIKROTIK_USERNAME Router username admin
MIKROTIK_PASSWORD Router password (required)
MIKROTIK_PORT RouterOS REST API port 80
MIKROTIK_USE_SSL Use HTTPS false
MIKROTIK_SSL_VERIFY Verify TLS certificate false
MIKROTIK__MCP__TRANSPORT MCP transport: stdio, sse, streamable-http stdio
MIKROTIK__MCP__HOST Bind host for non-stdio transports 0.0.0.0
MIKROTIK__MCP__PORT Bind port for non-stdio transports 8000

SSE example:

MIKROTIK__MCP__TRANSPORT=sse uvx mikrotik-rest-mcp

Tool Coverage

Registered domains include:

  • IP: addresses, routes, pools
  • DNS: resolver config, cache, static entries
  • Firewall: filter rules, NAT, address lists
  • Interfaces: VLAN, wireless, WireGuard
  • DHCP: servers, leases, pools
  • System: users, backups, logs, logging rules/actions

Tool naming convention follows mikrotik_<verb>_<resource>.

MCP Client Setup

Context Window Considerations

This server registers 100+ tools. When an MCP client loads all tool definitions into context at startup, this can consume a substantial portion of the available context window — leaving less room for conversation and reasoning.

Recommendations:

  • Use lazy-loading / tool search if your client supports it. This defers tool definition loading until a tool is actually needed, keeping context lean.
  • Claude Code supports this via MCP tool search. Enable it by setting CLAUDE_MCP_TOOL_SEARCH=true in your environment before launching Claude Code. This is the recommended approach when using Claude Code with this server.
  • If your client does not support lazy loading, consider whether you need all domains active. You can still use the server — just be aware of the context cost.

Claude Code

Add to your project-level .mcp.json (recommended) or global ~/.claude/settings.json:

{
  "mcpServers": {
    "mikrotik": {
      "command": "uvx",
      "args": ["mikrotik-rest-mcp"],
      "env": {
        "MIKROTIK_HOST": "192.168.88.1",
        "MIKROTIK_USERNAME": "admin",
        "MIKROTIK_PASSWORD": "yourpassword",
        "MIKROTIK_PORT": "80"
      }
    }
  }
}

With Nix:

{
  "mcpServers": {
    "mikrotik": {
      "command": "nix",
      "args": ["run", "github:alizdavoodi/mikrotik-rest-mcp"],
      "env": {
        "MIKROTIK_HOST": "192.168.88.1",
        "MIKROTIK_USERNAME": "admin",
        "MIKROTIK_PASSWORD": "yourpassword",
        "MIKROTIK_PORT": "80"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "mikrotik": {
      "command": "uvx",
      "args": ["mikrotik-rest-mcp"],
      "env": {
        "MIKROTIK_HOST": "192.168.88.1",
        "MIKROTIK_USERNAME": "admin",
        "MIKROTIK_PASSWORD": "yourpassword",
        "MIKROTIK_PORT": "80"
      }
    }
  }
}

With Nix:

{
  "mcpServers": {
    "mikrotik": {
      "command": "nix",
      "args": ["run", "github:alizdavoodi/mikrotik-rest-mcp"],
      "env": {
        "MIKROTIK_HOST": "192.168.88.1",
        "MIKROTIK_USERNAME": "admin",
        "MIKROTIK_PASSWORD": "yourpassword",
        "MIKROTIK_PORT": "80"
      }
    }
  }
}

OpenCode

Add to your OpenCode config (opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mikrotik": {
      "type": "local",
      "command": ["uvx", "mikrotik-rest-mcp"],
      "environment": {
        "MIKROTIK_HOST": "192.168.88.1",
        "MIKROTIK_USERNAME": "admin",
        "MIKROTIK_PASSWORD": "yourpassword",
        "MIKROTIK_PORT": "80"
      }
    }
  }
}

With Nix:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mikrotik": {
      "type": "local",
      "command": ["nix", "run", "github:alizdavoodi/mikrotik-rest-mcp"],
      "environment": {
        "MIKROTIK_HOST": "192.168.88.1",
        "MIKROTIK_USERNAME": "admin",
        "MIKROTIK_PASSWORD": "yourpassword",
        "MIKROTIK_PORT": "80"
      }
    }
  }
}

Architecture

server.py -> app.py -> FastMCP(lifespan)
                    -> tools.register_tools()
                    -> MikrotikConnectionManager
                    -> RouterOS REST API (/rest/...)
  • src/mikrotik_rest_mcp/server.py: entrypoint + transport selection
  • src/mikrotik_rest_mcp/app.py: FastMCP app + lifecycle wiring
  • src/mikrotik_rest_mcp/connection.py: async HTTP client and request handling
  • src/mikrotik_rest_mcp/tools/: domain tool modules

Troubleshooting

MCP error -32000: Connection closed

This usually means server startup failed early or env vars were missing in the spawned process.

Check raw startup error:

uvx mikrotik-rest-mcp 2>&1

Ensure MIKROTIK_* variables are set in your client's env/environment config block, or exported before launching the client.

Validate connectivity quickly

export MIKROTIK_HOST=192.168.88.1
export MIKROTIK_USERNAME=admin
export MIKROTIK_PASSWORD=yourpassword
curl -u "$MIKROTIK_USERNAME:$MIKROTIK_PASSWORD" "http://$MIKROTIK_HOST/rest/system/resource"

If you use HTTPS, switch the URL to https:// and apply your TLS verification settings.

Security Notes

  • Use a dedicated RouterOS user with minimum required permissions.
  • Prefer HTTPS (MIKROTIK_USE_SSL=true, MIKROTIK_PORT=443) in production.
  • Restrict RouterOS REST access by source IP/firewall rules.
  • Never commit secrets.

Metadata

Release files for mikrotik-rest-mcp 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mikrotik-rest-mcp 0.1.2
File Size Uploaded Provenance Actions
mikrotik_rest_mcp-0.1.2.tar.gz 27.7 kB With provenance Details for mikrotik_rest_mcp-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mikrotik-rest-mcp 0.1.2
File Interpreter ABI Platform Actions
mikrotik_rest_mcp-0.1.2-py3-none-any.whl Python 3 none any Details for mikrotik_rest_mcp-0.1.2-py3-none-any.whl

Total release size: 65.8 kB

Release files / mikrotik_rest_mcp-0.1.2.tar.gz

Download URL mikrotik_rest_mcp-0.1.2.tar.gz
Size 27.7 kB
Tags Source
SHA-256 checksum
How to use checksums
ea264a1654ab7d1bafc9ed1ac555df8645fefcad07486649b8580f7809897cbf
BLAKE2b-256 checksum
How to use checksums
1c401d6172cb1ca370e7617666d4431c6c303b6c42af8e208834a02158c23ace
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.

Transparency log

Release files / mikrotik_rest_mcp-0.1.2-py3-none-any.whl

Download URL mikrotik_rest_mcp-0.1.2-py3-none-any.whl
Size 38.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4225a363c26db03343c9facb8be2b025eaaa378dec3c33b5b44c5f7db37f30f0
BLAKE2b-256 checksum
How to use checksums
ad335c66e5851ec2c08f173ed71a8c7375583593939daaa822377eed95cd73c8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.

Transparency log

Security for mikrotik-rest-mcp 0.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mikrotik_rest_mcp-0.1.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 22, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page