RouterOS MCP Server

A Model Context Protocol (MCP) server for interacting with MikroTik RouterOS devices. This server provides AI assistants with comprehensive access to RouterOS devices through both API and SSH connections, with automatic fallback mechanisms for reliability.

Features

Multiple Connection Methods: API (port 8728), API with SSL (port 8729), and SSH (port 22)
Automatic Fallback: Tries connection methods in configurable order until successful
Multi-Device Support: Manage multiple RouterOS devices from a single MCP server
Comprehensive Tools: System info, interfaces, IP addresses, routes, neighbors, bridges, logs, config export, and ping
Smart Configuration Export: Automatically falls back to SSH when API permissions are insufficient
DNS Fallback: Supports fallback IP addresses when DNS resolution fails
Flexible Configuration: YAML-based device configuration with environment variable overrides
Type Safety: Full type hints and pydantic-based settings validation

Installation

Using UV (recommended)

cd routeros_mcp
uv sync

Using pip

cd routeros_mcp
pip install -e .

Configuration

Device Configuration

Create a devices.yaml file in one of these locations:

etc/devices.yaml (in the package directory)
Or specify a custom path with ROUTEROS_DEVICES_CONFIG environment variable

Example devices.yaml:

devices:
  - name: core-gw
    hostname: core-gw.example.com
    username: admin
    password: your-password
    disabled: false
    fallback_ip: 10.26.0.1  # Optional: used if DNS fails
    private_key: null        # Optional: SSH private key path

  - name: branch-router
    hostname: 192.168.1.1
    username: admin
    password: another-password
    disabled: false
    fallback_ip: null
    private_key: null

See etc/devices.yaml.example for a complete example.

Environment Variables (Optional)

Create a .env file to customize connection settings:

# RouterOS connection settings (defaults shown)
ROUTEROS_API_PORT=8728
ROUTEROS_API_SSL_PORT=8729
ROUTEROS_SSH_PORT=22
ROUTEROS_TIMEOUT=10
ROUTEROS_CONNECTION_ORDER=api,api_ssl,ssh

# Path to devices.yaml
ROUTEROS_DEVICES_CONFIG=/path/to/devices.yaml

# Logging level
ROUTEROS_LOG_LEVEL=INFO

See .env.example for all available options.

Usage

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "routeros": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/routeros-mcp",
        "run",
        "routeros-mcp"
      ]
    }
  }
}

See etc/claude_desktop_config_example.json for more options.

Command Line

# With UV
uv run routeros-mcp

# With Python
python -m routeros_mcp

Available Tools

Device Management

list_devices() - List all configured RouterOS devices
system_info(device_name) - Get system information (CPU, memory, uptime, version, etc.)

Network Information

interfaces(device_name, include_disabled) - List network interfaces with status
ip_addresses(device_name) - List IP addresses configured on interfaces
ip_routes(device_name, only_active) - List routing table entries
neighbors(device_name) - List discovered neighbors (CDP/LLDP)
bridges(device_name) - List Layer 2 bridge configurations

Monitoring

logs(device_name, topics, limit, offset) - Get device logs with pagination and filtering

Configuration & Diagnostics

config(device_name) - Get full configuration export (with automatic SSH fallback)
ping(device_name, address, count, size, interval, timeout) - Execute ping from device

Advanced

command(device_name, command, parameters_json) - Execute any RouterOS API command

Tool Examples

List Devices

Tool: list_devices
Returns: [{"name": "core-gw", "hostname": "192.168.1.1", ...}]

Get System Information

Tool: system_info
Parameters:
  - device_name: "core-gw"
Returns: {"success": true, "info": {"version": "7.12", "uptime": "2w3d", ...}}

Get Filtered Logs

Tool: logs
Parameters:
  - device_name: "core-gw"
  - topics: "ospf,error"  # Comma-separated regex patterns
  - limit: 20
  - offset: 0
Returns: {"logs": [...], "total_available": 150, "total_returned": 20}

Execute Custom API Command

Tool: command
Parameters:
  - device_name: "core-gw"
  - command: "/ip/firewall/filter/print"
  - parameters_json: "{}"
Returns: {"success": true, "result": [...]}

Ping from Router

Tool: ping
Parameters:
  - device_name: "core-gw"
  - address: "8.8.8.8"
  - count: 5
Returns: {"results": [...], "summary": {"sent": 5, "received": 5, "packet_loss_percent": 0}}

Available Resources

routeros://inventory - Real-time device inventory
routeros://device/{device_name}/status - Live device status
routeros://device/{device_name}/config - Current device configuration

Connection Methods

The server tries connection methods in the order specified by ROUTEROS_CONNECTION_ORDER (default: api, api_ssl, ssh):

API (port 8728): RouterOS API v2 without SSL - fastest method
API SSL (port 8729): RouterOS API v2 with SSL encryption
SSH (port 22): Fallback method using SSH commands

Notes on Permissions

Read-only API access: Most tools work with read-only API permissions
Configuration export: Requires read-write API permissions OR falls back to SSH automatically
Ping: Always uses SSH (not available via API)

Security Considerations

Store devices.yaml securely as it contains passwords
devices.yaml is in .gitignore by default
Consider using environment variables for sensitive data in production
API connections use plaintext authentication (required for RouterOS 6.43+)
SSL verification is disabled for API SSL connections (common for self-signed certs)

Troubleshooting

Device Not Found

Check that device name matches exactly in devices.yaml
Ensure device is not marked as disabled: true
Verify devices.yaml is in a searched location

Connection Failures

Verify hostname/IP is reachable: ping <hostname>
Check RouterOS API is enabled: /ip service print (look for api/api-ssl)
Verify SSH is enabled: /ip ssh print
Test credentials manually
Check firewall rules allow connections on required ports
Review server logs for detailed error messages

Configuration Export Fails

Requires read-write API permissions OR SSH access
Server automatically falls back to SSH if API fails
Check that user has /export command permissions

DNS Resolution Issues

Use fallback_ip in device configuration
Server automatically uses fallback IP if DNS fails

Development

Project Structure

routeros-mcp/
├── pyproject.toml
├── README.md
├── LICENSE
├── .env.example
├── .gitignore
├── etc/
│   ├── claude_desktop_config_example.json
│   └── devices.yaml.example
└── src/
    └── routeros_mcp/
        ├── __init__.py
        ├── __main__.py        # Entry point
        ├── server.py          # MCP server and tools
        ├── client.py          # RouterOS API/SSH client
        ├── settings.py        # Configuration management
        └── exceptions.py      # Custom exceptions

Running Tests

# Install development dependencies
uv sync --dev

# Run tests (if available)
pytest

# Type checking
mypy src/routeros_mcp

Adding New Tools

Add the core function to server.py (e.g., _routeros_new_feature())
Add MCP tool wrapper with @mcp.tool() decorator
Add comprehensive docstring with parameter descriptions
Update README.md with examples

RouterOS API Reference

Common API command paths (use with routeros_command):

/system/resource/print - System resources
/interface/print - Network interfaces
/ip/address/print - IP addresses
/ip/route/print - Routing table
/ip/firewall/filter/print - Firewall rules
/ip/firewall/nat/print - NAT rules
/routing/ospf/neighbor/print - OSPF neighbors
/routing/bgp/peer/print - BGP peers
/system/identity/print - System identity
/system/clock/print - System time
/log/print - System logs

For complete API documentation, see: https://help.mikrotik.com/docs/spaces/ROS/pages/47579160/API

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes with tests
Submit a pull request

Support

RouterOS Documentation: https://help.mikrotik.com/docs/spaces/ROS/
RouterOS API Documentation: https://help.mikrotik.com/docs/spaces/ROS/pages/47579160/API
MCP Documentation: https://modelcontextprotocol.io/

Changelog

0.1.0 (Initial Release)

Multi-device support with YAML configuration
API, API SSL, and SSH connection methods
Automatic fallback mechanisms
Comprehensive RouterOS tools and resources
Environment-based configuration
Full type safety with pydantic

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
etc		etc
src/routeros_mcp		src/routeros_mcp
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

RouterOS MCP Server

Features

Installation

Using UV (recommended)

Using pip

Configuration

Device Configuration

Environment Variables (Optional)

Usage

Claude Desktop

Command Line

Available Tools

Device Management

Network Information

Monitoring

Configuration & Diagnostics

Advanced

Tool Examples

List Devices

Get System Information

Get Filtered Logs

Execute Custom API Command

Ping from Router

Available Resources

Connection Methods

Notes on Permissions

Security Considerations

Troubleshooting

Device Not Found

Connection Failures

Configuration Export Fails

DNS Resolution Issues

Development

Project Structure

Running Tests

Adding New Tools

RouterOS API Reference

License

Contributing

Support

Changelog

0.1.0 (Initial Release)

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages