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_CONFIGenvironment 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 devicessystem_info(device_name)- Get system information (CPU, memory, uptime, version, etc.)
Network Information
interfaces(device_name, include_disabled)- List network interfaces with statusip_addresses(device_name)- List IP addresses configured on interfacesip_routes(device_name, only_active)- List routing table entriesneighbors(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 inventoryrouteros://device/{device_name}/status- Live device statusrouteros://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.yamlsecurely as it contains passwords devices.yamlis in.gitignoreby 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.yamlis 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
/exportcommand permissions
DNS Resolution Issues
- Use
fallback_ipin 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