Content
# 🚀 iKuai MCP Server
[](https://pypi.org/project/ikuai-mcp-server/)
[](https://www.python.org/)
[](LICENSE)
[](https://github.com/gxxHuang/ikuai-mcp-server/actions/workflows/test.yml)
[](https://modelcontextprotocol.io/)
**iKuai Router Full-Function MCP Server** — Let AI assistants directly control your iKuai router.
> 229 tools · 149 API endpoints · 100% Web backend feature coverage
## Prerequisites
- **Python 3.10+**
- **iKuai Router** (Enterprise version 4.x; some APIs not available for free version)
- **AI Client**: Claude Desktop / Cursor / VS Code + GitHub Copilot
---
## 📦 Installation
```bash
pip install ikuai-mcp-server
```
## ⚡ Quick Start
### 1. Configuration
```bash
cp .env.example .env
# Edit .env, fill in router information:
# IKUAI_URL=http://192.168.9.1
# IKUAI_USERNAME=admin
# IKUAI_PASSWORD=your password
```
### 2. Connect to AI Client
**Claude Desktop** — Edit `claude_desktop_config.json`:
```json
{
"mcpServers": {
"ikuai": {
"command": "ikuai-mcp",
"args": [],
"env": {
"IKUAI_URL": "http://192.168.9.1",
"IKUAI_USERNAME": "admin",
"IKUAI_PASSWORD": "your password"
}
}
}
}
```
**Cursor** — Create `.cursor/mcp.json`:
```json
{
"mcpServers": {
"ikuai": {
"command": "ikuai-mcp",
"args": [],
"env": {
"IKUAI_URL": "http://192.168.9.1",
"IKUAI_USERNAME": "admin",
"IKUAI_PASSWORD": "your password"
}
}
}
}
```
### 3. Usage
After configuration, naturally converse with AI client:
- "Check current router status" → CPU, memory, traffic, version
- "List all online devices" → terminal IP/MAC/traffic overview
- "Limit speed for 192.168.9.100 to 10MB/s" → add terminal speed limit
- "Add port mapping 8080 to internal 192.168.9.50" → one-click port mapping
- "Change Wi-Fi password to xxxxxxxx" → change password
- "Enable SSH" → enable hidden SSH service
### HTTP Mode (without AI client)
```bash
python -m ikuai_mcp.server --transport http --port 8000
# Access http://localhost:8000
```
Suitable for script calls, custom integrations, or with other HTTP MCP clients.
---
## 📊 Feature Coverage
| Module | Tool count | Main features |
|------|------------|-------------|
| 🔍 System Monitoring | 17 | System overview, circuit/terminal/behavior/load/distribution monitoring, downstream devices |
| 🌐 Network Configuration | 58 | WAN/LAN, IPv6, VLAN, DHCP, DNS, static routing, port mapping, NAT, UPnP, DDNS |
| 🛡️ Security Control | 39 | ACL, connection limit, ARP, MAC control, URL browsing control, URL control, application protocol control |
| ⚡ Traffic Control | 21 | Intelligent traffic control, IP/MAC speed limit, multi-line load, protocol/port/domain distribution |
| 🔐 Authentication and Billing | 28 | PPPoE, Web authentication, VPN server/client, package, notification push |
| 📡 Wireless Service | 16 | AP management, Wi-Fi settings, channel scanning, Mesh |
| 🔧 Advanced Service | 21 | Ping/Traceroute/iPerf/speed test/WOL, packet capture, SNMP |
| 📋 Log Center | 11 | Authentication/ARP/DHCP/DDNS/operation logs, alarms |
| ⚙️ Device Settings | 18 | SSH/Telnet/FTP switches, firmware upgrade, configuration snapshot, password management |
---
## 🐳 Docker
```bash
# 1. Configure .env (required! Otherwise, password will be empty in container)
cp .env.example .env
# Edit .env
# 2. Start
docker-compose up -d
```
---
## 🧪 Development
```bash
pip install -e ".[dev]"
make test # Run tests
make lint # Code check
```
## 📁 Project Structure
```
ikuai-mcp-server/
├── src/ikuai_mcp/
│ ├── server.py # FastMCP entry
│ ├── client.py # API client
│ └── tools/ # 9 tool modules
├── tests/ # pytest tests
├── .github/workflows/ # CI/CD
└── Dockerfile # Docker image
```
## 🔧 Compatibility
| Router | Firmware | Status |
|--------|----------|--------|
| IK-Q series | 4.x Enterprise | ✅ Compatible |
| IK-G series | 3.x+ | ⚠️ Partially compatible |
| Free version | 3.x | ⚠️ Limited API |
## 🆘 Troubleshooting
| Issue | Solution |
|------|----------|
| Can't connect to router | Check if `IKUAI_URL` is correct, and if computer and router are on the same network |
| Authentication failed | Log in with browser to confirm password is correct; check `IKUAI_PASSWORD` in `.env` |
| `.env` not loaded | Ensure `.env` is in project root, or directly write environment variables to Claude Desktop's `env` field |
| Python version too low | Requires Python 3.10+, run `python --version` to confirm |
| Certain features error | Free version/old firmware have limited API, upgrade to Enterprise 4.x |
| MCP tool not displayed | Restart Claude Desktop / Cursor and try again |
## 🤝 Contribution
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
## 📜 License
MIT License — See [LICENSE](LICENSE).
## ⚠️ Security Notice
- Dangerous operations (reboot/firmware upgrade/factory reset) require `confirm=True` secondary confirmation
- Password managed through `.env`, do not submit to Git
- Only supports local network connection, will not expose to public network
