# MikroTik MCP Server

MCP server for MikroTik RouterOS with:

- multi-router support
- environment-based auto-load
- split read/write architecture
- selectable runtime modes: `readonly`, `safe-write`, `full`

## Current Architecture

Key modules:

- [mikrotik_mcp/config.py](/C:/Users/PKO-X1-Yoga-G6/Documents/proj_mcp_mikrotik/mikrotik_mcp/config.py)
- [mikrotik_mcp/manager.py](/C:/Users/PKO-X1-Yoga-G6/Documents/proj_mcp_mikrotik/mikrotik_mcp/manager.py)
- [mikrotik_mcp/read_service.py](/C:/Users/PKO-X1-Yoga-G6/Documents/proj_mcp_mikrotik/mikrotik_mcp/read_service.py)
- [mikrotik_mcp/write_service.py](/C:/Users/PKO-X1-Yoga-G6/Documents/proj_mcp_mikrotik/mikrotik_mcp/write_service.py)
- [mikrotik_mcp/tools.py](/C:/Users/PKO-X1-Yoga-G6/Documents/proj_mcp_mikrotik/mikrotik_mcp/tools.py)
- [mikrotik_mcp/server.py](/C:/Users/PKO-X1-Yoga-G6/Documents/proj_mcp_mikrotik/mikrotik_mcp/server.py)
- [mikrotik_mcp/entrypoint.py](/C:/Users/PKO-X1-Yoga-G6/Documents/proj_mcp_mikrotik/mikrotik_mcp/entrypoint.py)
- [mikrotik_mcp/hermes_entrypoint.py](/C:/Users/PKO-X1-Yoga-G6/Documents/proj_mcp_mikrotik/mikrotik_mcp/hermes_entrypoint.py)

Architecture notes:

- [ARCHITECTURE.md](/C:/Users/PKO-X1-Yoga-G6/Documents/proj_mcp_mikrotik/ARCHITECTURE.md)

## Runtime Modes

- `readonly`
  - registers only read tools
  - read tools auto-connect on first use when routers are pre-defined in env
  - safest mode for AI agents
- `safe-write`
  - registers all read tools
  - registers only a small safe write subset: `add_router`, `connect_router`, `backup_config`
- `full`
  - registers both read and write tools

Mode reference:

- [MODE_SELECTION.md](/C:/Users/PKO-X1-Yoga-G6/Documents/proj_mcp_mikrotik/MODE_SELECTION.md)

## Multi-Router Setup

Recommended approach: set `MIKROTIK_ROUTERS` once and let the server auto-load routers every time it starts.

Example:

```json
{
  "rb4011": {
    "host": "192.168.100.1",
    "username": "admin",
    "password": "change-me-4011",
    "port": 8728
  },
  "rb2011": {
    "host": "192.168.88.1",
    "username": "admin",
    "password": "change-me-2011",
    "port": 8728
  }
}
```

More details:

- [MULTI_ROUTER_ENV.md](/C:/Users/PKO-X1-Yoga-G6/Documents/proj_mcp_mikrotik/MULTI_ROUTER_ENV.md)

## Launching The Server

Recommended subprocess entrypoints:

```bash
python -m mikrotik_mcp.entrypoint
python -m mikrotik_mcp.hermes_entrypoint
```

Set runtime via environment variables such as:

```text
MIKROTIK_MODE=readonly|safe-write|full
MIKROTIK_ROUTERS=<json>
```

## Installation

Setup guide:

- [INSTALL.md](/C:/Users/PKO-X1-Yoga-G6/Documents/proj_mcp_mikrotik/INSTALL.md)

## Testing

Testing guide:

- [TESTING.md](/C:/Users/PKO-X1-Yoga-G6/Documents/proj_mcp_mikrotik/TESTING.md)

Quick commands:

```bash
python -m pytest -q
python -m pytest -q -m regression
python -m pytest -q -m scenario
python -m pytest -q -m acceptance
```

## Security Guidance

For AI agents:

1. Prefer `readonly` mode by default.
2. Use `safe-write` only when backup/connect workflows are required.
3. Use `full` only for supervised admin workflows.

## Tool Coverage

Read surface includes:

- routers
- connectivity test
- system info
- interfaces
- IP addresses
- firewall rules
- DHCP leases and DHCP info
- logs, log topics, log summary
- NAT rules
- routes
- users
- wireless interfaces and registration

Write surface includes:

- add router
- connect router
- add/remove IP
- add/update/delete/move firewall rules
- add route
- update/delete NAT rules
- backup config
- run command