Keenetic-router-plugin

Keenetic 라우터를 RCI를 통해 제어할 수 있게 해주는 플러그인(MCP 서버 + skill)입니다. RCI는 라우터 웹 인터페이스가 사용하는 것과 동일한 API입니다. 로컬 네트워크를 통해 직접 작동하며 클라우드를 거치지 않습니다. MCP 서버는 독립적이며 모든 MCP 클라이언트(예: Codex)에서 작동합니다. skill(Keenetic에 대한 AI용 도메인 지식)은 Claude Code 플러그인 생태계에서만 작동합니다.

KeeneticOS 5.0.12에서 테스트되었습니다. 다른 모델/펌웨어에서는 특정 RCI 경로가 다를 수 있습니다. 작업을 시작하기 전에 npm run smoke를 실행하세요 (read-only이며 라우터의 어떤 것도 변경하지 않습니다).

이 플러그인을 통해 AI가 할 수 있는 것과 할 수 없는 것

읽기 — 확인 없이 언제든 가능: 펌웨어 버전, WAN 상태, 인터페이스 목록, 연결된 기기, Wi-Fi 클라이언트, 포트 포워딩, 경로, DHCP 예약, VPN 인터페이스, 전체 구성 내보내기(export_config).

변경 — AI가 명시적으로 confirm: true를 전달한 경우에만: Wi-Fi 비밀번호 변경, 액세스 포인트 켜기/끄기, 포트 포워딩 추가/삭제, 경로 추가/삭제, 이미 구성된 VPN 터널에 네트워크 연결/해제, .bat 파일에서 경로 일괄 적용. confirm: true가 없으면 호출이 거부됩니다. AI에게 먼저 dryRun: true로 실행하도록 요청할 수 있습니다. 그러면 아무것도 적용하지 않고 무엇이 라우터로 전송될지 표시합니다.

위험한 작업 — 서버 구성에 ALLOW_DESTRUCTIVE=true가 추가로 필요: 라우터 재부팅. 이 플래그가 켜져 있지 않으면 confirm: true를 주더라도 AI로 라우터를 재부팅할 수 없습니다.

플러그인이 원칙적으로 할 수 없는 일 (구현되지 않음): VPN(VPN) 터널을 처음부터 생성(WireGuard/OpenVPN/IPsec), 공장 초기화, 펌웨어 업데이트.

모든 write/destructive 호출(적용된 것, 거부된 것, 오류로 실패한 것)은 audit.log에 기록됩니다.

Related MCP server: AsusWRT MCP Server

설치

Node.js 20+가 필요합니다.

1. 프로젝트를 클론하고 의존성을 설치하세요:

npm install
npm run build

2. 같은 폴더에 .env.example을 .env로 복사하고 변수를 입력하세요:

ROUTER_HOST=192.168.1.1        # LAN-адрес роутера (в свойствах сети — "основной шлюз")
ROUTER_PORT=80
ROUTER_LOGIN=имя_пользователя
ROUTER_PASSWORD=пароль_пользователя
ALLOW_DESTRUCTIVE=false        # true — разрешить reboot_router

.env 대신 서버 등록 시 --env 플래그로 동일한 값을 전달할 수도 있습니다 — 아래 참조.

3. 연결을 확인하세요 (read-only, 라우터의 어떤 것도 변경하지 않습니다):

npm run smoke

특정 요청이 오류를 반환한다면, 해당 모델/펌웨어에서 RCI 경로가 다른 것입니다. AI로 작업을 시작하기 전에 src/capabilities/*.ts 경로를 수정하세요.

Claude Code에 연결

플러그인으로 (권장 — skill 포함):

claude --plugin-dir "<путь-к-проекту>"

영구 연결(한 세션만이 아니라)을 위해 프로젝트를 git 리포지토리나 로컬 마켓플레이스에 올린 후 /plugin install을 사용하세요.

서버만 사용, skill 제외:

claude mcp add --transport stdio --scope user keenetic -- node "<путь-к-проекту>/dist/index.js"

.env를 만들지 않았다면 자격 증명을 여기에 직접 입력하세요:

claude mcp add --transport stdio --scope user \
  --env ROUTER_HOST=192.168.1.1 --env ROUTER_LOGIN=имя_пользователя --env ROUTER_PASSWORD=его_пароль \
  keenetic -- node "<путь-к-проекту>/dist/index.js"

연결 확인: claude mcp list, claude mcp get keenetic 또는 세션 안에서 /mcp.

이제 대화에서 예를 들어 "라우터에 연결된 기기 보여줘" 또는 "게스트 Wi-Fi 비밀번호 변경해줘"라고 요청할 수 있습니다.

Codex와의 연결

~/.codex/config.toml에:

[mcp_servers.keenetic]
command = "node"
args = ["<путь-к-проекту>/dist/index.js"]

보안

가드 모델(confirm/dryRun/ALLOW_DESTRUCTIVE)은 AI의 우발적이고 부주의한 행동을 방지합니다. 라우터 비밀번호 자체는 보호하지 않습니다. .env나 구성 파일이 남의 손에 들어가면 해당 비밀번호만으로 서버와 모든 제한을 우회해 라우터에 직접 접근할 수 있습니다.

• **export_config**는 공식적으로 read-only이지만 비밀정보를 평문 또는 약하게 난독화된 형태로 반환합니다(비밀번호 해시, WPA-PSK, WireGuard 매개변수). 라우터 웹 인터페이스에서 "저장" 버튼 뒤에 숨겨진 정보와 동일하지만, 이제 AI 대화에 노출됩니다. 도구 자체가 호출 전에 AI가 사전 경고하도록 요청합니다.

• 별도의 사용자 지정 — 가능하면 admin을 사용하지 말고, 라우터 웹 인터페이스(시스템 → 사용자)에서 서비스용 별도 사용자를 만드세요. 단, 일부 작업(특히 set_wifi_password/set_wifi_enabled)은 Keenetic에서 admin만 허용합니다. 해당 작업이 필요하면 admin으로 하되, 새롭고 고유한 비밀번호를 사용하세요.

• RCI/웹 관리자 인터페이스를 인터넷에 노출하지 마세요 — 원격 액세스, 관리 접근 가능한 KeenDNS, 또는 이 계정에 대한 웹 관리자 인터페이스의 포트 포워딩을 활성화하지 마세요. 기본적으로 Keenetic은 외부 접근이 차단되어 있습니다.

• .env에 대한 접근을 OS 수준에서 제한하세요(macOS/Linux: chmod 600 .env, Windows: 파일 속성 → '보안'). 파일은 이미 .gitignore에 있습니다.

• ** 다른 비밀번호와 겹치지 않는 길고 고유한 비밀번호를 사용하세요.

개발

npm run dev     # запуск сервера напрямую через tsx, без сборки
npm test        # unit-тесты (без обращения к реальному роутеру)
npm run smoke   # live read-only проверка на реальном роутере из .env

버전 및 릴리스

프로젝트 버전(package.json, .claude-plugin/plugin.json)은 master 브랜치로 push하면 자동으로 증가합니다. GitHub Actions가 semantic-release를 실행하고, 커밋 메시지(Angular convention)에 따라 버전 수준을 결정합니다:

• fix: ... → patch

• feat: ... → minor

• feat!: ... / BREAKING CHANGE: ... (커밋 본문) → major

• chore:, docs:, refactor:, test: 등 → 릴리스 생성되지 않음

• — (주의:불필요한 주석 아님)

버전을 수동으로 올리거나 편집하지 않습니다. 완전히 커밋 기록에서 자동으로 파생됩니다.