Robot NXT Control MCP

USB/WinUSB로 Windows 11에 연결되는 호환 프로그래머블 브릭 하드웨어를 위한 로컬 MCP 서버입니다.

호환성 및 상표

이 독립 프로젝트는 LEGO Group와 제휴하지 않으며, LEGO Group의 후원이나 보증을 받지 않습니다. LEGO, MINDSTORMS 및 NXT는 LEGO Group의 상표입니다. 이 문서에서는 호환 하드웨어, 소프트웨어, 프로토콜 및 타사 종속성을 식별하기 위해서만 사용됩니다. 이들은 이 프로젝트의 이름, 서버 식별자 또는 플러그인 식별자의 일부가 아닙니다.

이전 릴리스에서 마이그레이션

기존 플러그인 및 MCP 서버 식별자는 robot-nxt-control로 대체되었으며, 실행 파일 이름은 이제 robot-nxt-control-mcp, robot-nxt-control-mcp-stdio, robot-nxt-control-mcp-http입니다. 이 변경 사항을 가져온 후 editable 패키지를 다시 설치하고 이전 MCP 구성 항목을 아래 예시로 교체하세요.

Related MCP server: KentraBOT MCP Server

Claude Desktop 또는 Codex desktop에 설치 (Windows)

먼저 Windows 11 설치를 완료하세요. 이 데스크톱 앱은 MCP 서버를 직접 시작하므로 robot-nxt-control-mcp-stdio.exe를 수동으로 실행하지 마세요. 예시는 이 저장소가 C:\Users\lukas\workspace\NXT-MCP에 있다고 가정합니다. 체크아웃 위치가 다른 경우 모든 경로에서 해당 부분을 교체하세요.

Claude Desktop

1. Claude Desktop을 완전히 종료하세요(트레이 아이콘 포함).

2. %APPDATA%\Claude\claude_desktop_config.json을 엽니다. 파일이 없으면 만듭니다. 이미 mcpServers 객체가 있다면 아래 robot-nxt-control 항목만 추가하세요.

3. 파일을 저장하고 Claude Desktop을 다시 시작하세요. 서버가 설정 → 개발자 → MCP 서버에 표시되어야 합니다.

{
  "mcpServers": {
    "robot-nxt-control": {
      "command": "C:\\Users\\lukas\\workspace\\NXT-MCP\\.venv\\Scripts\\robot-nxt-control-mcp-stdio.exe",
      "cwd": "C:\\Users\\lukas\\workspace\\NXT-MCP"
    }
  }
}

복사하여 사용할 수 있는 동일한 구성은 packaging/claude-desktop/mcp.json에 있습니다.

Codex desktop

Codex desktop 호스트와 Codex CLI는 %USERPROFILE%\.codex\config.toml의 공유 MCP 구성을 사용합니다. 이 블록을 추가하고(또는 아래의 동일한 codex mcp add 명령을 실행한 다음) Codex 앱을 다시 시작하세요:

[mcp_servers.robot-nxt-control]
command = "C:\\Users\\lukas\\workspace\\NXT-MCP\\.venv\\Scripts\\robot-nxt-control-mcp-stdio.exe"
cwd = "C:\\Users\\lukas\\workspace\\NXT-MCP"
startup_timeout_sec = 10
tool_timeout_sec = 120

PowerShell 대안:

codex mcp add robot-nxt-control -- C:\Users\lukas\workspace\NXT-MCP\.venv\Scripts\robot-nxt-control-mcp-stdio.exe
codex mcp list

ChatGPT 데스크톱 MCP UI의 경우: 설정 → MCP 서버 → 서버 추가를 선택하고, STDIO를 선택한 다음, robot-nxt-control을 입력하고, 명령어로 동일한 실행 파일을 사용하고, 저장한 후 앱을 다시 시작하세요. 로컬 Codex 클라이언트는 STDIO와 Streamable HTTP를 모두 지원하며 이 MCP 구성을 공유합니다. 공식 OpenAI MCP 문서

첫 번째 확인

새 채팅을 열고 nxt_info를 요청하세요. 연결할 수 없으면 먼저 ./.venv/Scripts/nxt-test.exe --log-level=debug로 로봇이 작동하는지 확인하세요. 그런 다음 구성된 모든 경로가 존재하고 NXT가 켜져 있는지 확인하세요. 이동 도구는 실제 하드웨어를 제어합니다. nxt_info 또는 query_all_state로 시작한 다음 낮은 power와 범위가 제한된 이동 명령을 사용하세요.

MCP 전송 방식, 호스트 및 검증

동일한 create_server() 팩토리가 두 전송 방식을 모두 지원합니다. robot-nxt-control-mcp-stdio는 Claude Desktop, Claude Code, Codex CLI, Codex desktop 및 로컬 Codex 플러그인을 위한 로컬 프로세스 전송 방식입니다. 프로토콜 트래픽을 stdout에만 기록합니다.

제공된 JSON을 시작 구성으로 사용하고, 체크아웃을 이동한 후 절대 작업 공간 경로를 교체하세요:

• Claude Desktop: packaging/claude-desktop/mcp.json

• Claude Code 플러그인: packaging/claude-code/

• Codex 로컬 플러그인: C:\Users\lukas\plugins\robot-nxt-control (개인 마켓플레이스에서 생성됨)

프로토콜 테스트를 위해 루프백에서 Streamable HTTP를 시작하세요:

.\.venv\Scripts\robot-nxt-control-mcp-http.exe --port 8000
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8000/mcp --method tools/list
npx @modelcontextprotocol/conformance server --url http://127.0.0.1:8000/mcp --suite active

.\.venv\Scripts\python.exe -m pytest로 저장소 검사를 실행하세요. 여기에는 컨트롤러 및 동작 테스트 외에도 프로세스 내 MCP 협상, tools/list, 어노테이션 및 tools/call 테스트가 포함됩니다. conformance-baseline.yml은 이 특화된 하드웨어 서버가 광고하지 않는 선택적 MCP 기능이 필요한 일반적인 시나리오만 기록합니다. 각 항목은 번다운 어서션이므로 실행기가 오래된 항목을 표시합니다.

robot-nxt-control-mcp-http는 기본적으로 127.0.0.1에 바인딩되며, NXT_MCP_ALLOW_REMOTE=true가 명시적으로 설정되지 않으면 루프백이 아닌 바인딩을 거부합니다. 클라우드 클라이언트는 USB NXT에 직접 연결할 수 없습니다. 이 서버를 로봇 옆에서 실행하고, OAuth/토큰 검증, 권한 부여, 감사 로그 및 네트워크 제한을 갖춘 프로덕션 HTTPS 리버스 프록시를 Streamable HTTP 엔드포인트 앞에 배치하세요. 환경 변수 재정의만으로 USB 제어 엔드포인트를 공개적으로 노출하지 마세요.

모듈 설계, MCP 및 동작 실행 흐름, USB 스택, 안전 모델 및 Mermaid 다이어그램은 ARCHITECTURE.md를 참조하세요.

Windows 11 설치

Python 3.11 x64를 사용하세요. PowerShell에서:

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[test]"

1. Zadig로 NXT 장치 드라이버 설치

NXT를 켜고 USB로 연결하세요. PowerShell에서 Windows가 일반 모드 장치를 인식하는지 확인하세요:

Get-PnpDevice -PresentOnly |
  Where-Object InstanceId -match 'VID_0694&PID_0002' |
  Format-List Status,FriendlyName,InstanceId,Problem

하드웨어 ID에는 USB\VID_0694&PID_0002가 포함되어야 합니다. Problem이 CM_PROB_FAILED_INSTALL이거나 장치 관리자에 Code 28이 표시되면 드라이버가 없는 것입니다.

1. Zadig는 https://zadig.akeo.ie/에서만 다운로드하세요.

2. Zadig를 관리자 권한으로 실행하세요.

3. 옵션 > 모든 장치 나열을 선택하세요.

4. USB ID가 정확히 0694:0002인 항목을 선택하세요. 표시된 장치 이름만이 아니라 ID를 사용하세요.

5. 드라이버 선택기에서 WinUSB를 선택하세요.

6. 드라이버 설치 또는 드라이버 교체를 클릭하세요.

7. NXT를 분리했다가 다시 연결하고, 전원을 켠 상태로 두세요.

03EB:6124를 선택하지 마세요. 그것은 NXT 부트로더/펌웨어 업데이트 모드입니다. 관련 없는 USB 장치의 드라이버를 교체하지 마세요. WinUSB를 설치하면 LEGO/Fantom 드라이버가 복원될 때까지 기존 LEGO NXT-G 소프트웨어가 브릭과 통신하지 못할 수 있습니다.

2. PyUSB용 x64 libusb 런타임 설치

WinUSB는 Windows 장치 드라이버입니다. PyUSB는 별도로 사용자 공간 libusb-1.0.dll이 필요합니다. 저장소에는 공식 libusb 1.0.30 아카이브를 다운로드하고 SHA-256을 확인한 다음, 이 환경의 python.exe 옆에 VS2022 x64 DLL을 설치하는 헬퍼가 포함되어 있습니다:

.\scripts\install-libusb-runtime.ps1

헬퍼는 PATH에 7z.exe가 필요합니다. 수동으로 설치하려면 공식 libusb GitHub 릴리스에서 libusb-1.0.30.7z를 다운로드하고 VS2022\MS64\dll\libusb-1.0.dll을 추출한 다음 .venv\Scripts\libusb-1.0.dll로 복사하세요. 64비트 Python에서 MS32 DLL을 사용하지 마세요.

런타임을 별도로 확인하세요:

$env:PATH = "$PWD\.venv\Scripts;$env:PATH"
.\.venv\Scripts\python.exe -c "import usb.backend.libusb1 as b; assert b.get_backend() is not None; print('libusb OK')"

MCP 서버는 가상 환경 Python 옆에 설치된 DLL을 자체 검색 경로에 자동으로 추가합니다. nxt-test.exe는 외부 NXT-Python 명령이므로, 사용하기 전에 먼저 위의 $env:PATH 줄을 실행하거나 가상 환경을 활성화하세요.

3. 브릭 테스트

MCP 전에 하드웨어를 확인하세요:

.\.venv\Scripts\nxt-test.exe --log-level=debug

테스트가 성공하면 브릭 이름, 배터리 잔량, 프로토콜 버전 및 펌웨어 버전이 출력됩니다. 여전히 브릭이 없다고 보고하면 장치 관리자에서 0694:0002 장치를 다시 확인하고 해당 드라이버가 WinUSB인지 확인하세요.

펌웨어

NXT가 정상적으로 부팅되고 Windows에 VID 0694 / PID 0002가 표시되면 펌웨어 설치나 업데이트가 필요하지 않습니다. MCP 서버는 표준 NXT 직접 명령을 사용하며 nxt_info를 통해 설치된 펌웨어 및 프로토콜 버전도 보고합니다.

브릭이 정상적으로 부팅되지 않고 Windows에 Atmel SAM-BA 펌웨어 업데이트 모드인 VID 03EB / PID 6124가 대신 표시되는 경우에만 펌웨어 복구를 수행하세요. 복구는 브릭 펌웨어를 지우고 다시 쓰며 일반적인 MCP 설정 범위를 벗어납니다:

1. 03EB:6124에 일반 NXT WinUSB 규칙을 설치하지 마세요.

2. 원래 LEGO MINDSTORMS NXT 소프트웨어에 필요한 펌웨어 업데이트 드라이버를 복원/사용하세요.

3. 해당 소프트웨어에서 공식 NXT 펌웨어 이미지와 함께 도구 > NXT 펌웨어 업데이트를 사용하세요.

4. 복구 후 브릭의 전원을 껐다 켜세요. 0694:0002로 돌아와야 합니다. 필요한 경우 해당 일반 모드 장치에 WinUSB를 다시 설치하세요.

NXT-Python은 의도적으로 펌웨어 플래싱을 제공하지 않습니다. NoBackendError, Code 28 또는 MCP 연결 실패를 해결하기 위한 목적으로만 펌웨어 부팅 모드를 호출하거나 업데이트를 시도하지 마세요.

그런 다음 MCP Inspector를 여세요:

.\.venv\Scripts\mcp.exe dev src\nxt_mcp\server.py

로컬 MCP 호스트의 경우 명령어를 .venv\Scripts\robot-nxt-control-mcp.exe로, 작업 디렉터리를 저장소로 하여 stdio 서버를 구성하세요.

서버를 시작하기 전에 브릭에 연결된 센서를 선언하면 전체 브릭 스냅샷이 타입이 지정된 판독값을 즉시 반환할 수 있습니다:

$env:NXT_SENSOR_MAP = "1:touch,2:light,4:ultrasonic"
.\.venv\Scripts\robot-nxt-control-mcp.exe

read_sensor 또는 센서 기반 모터 명령을 호출하면 이후 스냅샷을 위해 해당 포트의 유형도 기억합니다.

고수준 도구

• move_motor_relative(port="C", power=40, degrees=2000)은(는) C를 인코더 기준 2000도만큼 앞으로 이동시킵니다. 반대 방향에는 음수 power를 사용하세요. 어댑터는 타이트한 USB 인코더 루프를 사용합니다. NXT-Python의 표준 turn() 루프는 작은 이동에 대해 폴링 속도가 너무 느리기 때문입니다. 45도 정도의 이동에는 20과 같은 더 낮은 power를 사용하세요.

• zero_motor_position(port="C")은(는) 현재 C 인코더 위치를 절대 0으로 정의합니다. move_motor_absolute(port="C", target_degrees=-90, power=20)은(는) 그런 다음 -90으로 이동합니다. 절대 이동은 대상에서 방향을 파생하며, 해당 power는 양의 크기입니다.

• motor_position(port="C")은(는) 절대/프로그램 상대 인코더 위치와 원시 타코 카운터를 보고합니다.

• run_motor(port="C", power=-30)은(는) 정지 명령 또는 제한된 동작이 이를 멈출 때까지 음수 방향으로 계속 실행됩니다. regulated=true인 경우 power는 NXT 조정 속도 설정이지 보정된 초당 도 값이 아닙니다.

• run_motors(ports=["B", "C"], powers=[30, -30])은(는) 한 번의 MCP 호출로 모터 그룹을 시작합니다. stop_motors, move_motors_relative, move_motors_absolute도 같은 방식으로 그룹에 작동합니다. 리스트는 위치 기반입니다. 각 power/degree 값은 같은 인덱스의 포트에 속합니다.

• run_motor_until_sensor(port="B", power=40, sensor_port=1, sensor_type="touch", condition="pressed")은(는) 터치 S1이 눌릴 때까지 B를 실행합니다.

• run_motors_until_sensor(ports=["B", "C"], powers=[40, 40], sensor_port=4, sensor_type="ultrasonic", condition="lte", threshold=20)은(는) 장애물이 최대 20cm 거리에 있을 때까지 두 모터를 구동한 다음 전체 그룹을 정지시킵니다.

• run_motor_until_sensor(port="B", power=40, sensor_port=4, sensor_type="ultrasonic", condition="lte", threshold=20)은(는) 장애물이 최대 20cm 거리에 있을 때까지 B를 실행합니다.

• query_all_state(format="json")은(는) 브릭, 모든 모터 포트 및 모든 센서 포트의 간결한 텍스트 스냅샷 하나를 반환합니다. 구조화된 데이터에는 format="json"을 사용하세요.

• cycle_motor_on_touch(port="C", touch_port=1, cycles=5)은(는) S1이 눌릴 때까지 전진하고, 해제될 때까지 후진하며, 다섯 번 반복한 후 성공하면 비프음을 냅니다. 각 누름 및 해제 단계에는 자체 시간 제한과 인코더 이동 상한이 있습니다.

모든 센서 기반 동작에는 시간 제한과 인코더 이동 제한이 있습니다. 두 제한 중 하나에 도달하면 모터가 정지하고 이유와 함께 ok: false가 반환됩니다. 센서 또는 USB 읽기가 실패해도 모터가 정지합니다.

확장 진단, 저장소 및 원격 측정

• motor_state(port)는 조절 상태, 실행 상태, 타코미터 값, 구성된 출력 상태를 보고합니다. drive_sync(left_port, right_port, power, turn_ratio=0)는 차동 구동 쌍에 대해 NXT 펌웨어 동기화 조절을 사용합니다. wait_motors(...)는 데드라인이 있고 제한 시간이 지나면 해당 포트를 정지합니다.

• read_sensor_raw(port, sensor_type?), wait_sensor(...), sensor_stream(...)은 제한된 진단, 디바운스된 센서 대기, 유한 샘플을 제공합니다.

• 조도, 색상, 초음파 센서의 경우 zero_sensor_reference(port, sensor_type)을 호출한 다음 read_sensor_relative(port, sensor_type)을 호출하세요. 이 함수는 캡처된 0점으로부터의 변화량과 절대값을 반환합니다. 색상 센서는 의미 있는 차감을 위해 반사광 강도(이산적인 빨강/파랑 등의 라벨이 아닌)를 사용합니다.

• log_start, log_status, log_stop, log_export은 제한된 호스트 측 CSV 텔레메트리를 제공합니다. 유효한 채널은 battery_mv, motor:A부터 motor:C, 그리고 sensor:1:touch(또는 다른 지원되는 센서 유형/포트)입니다.

• list_files, read_file, write_file, delete_file은 제한된 NXT 사용자 파일을 관리합니다. 쓰기는 .txt, .csv, .dat, .rso로 제한됩니다. 사운드 재생은 play_sound_file(name)과 stop_sound()을 사용합니다.

• mailbox_send / mailbox_receive는 최대 58 UTF-8 바이트 메시지를 지원합니다. i2c_transaction은 16바이트 요청 및 응답 페이로드로 제한되는 옵트인 저속 작업입니다. set_brick_name과 keep_alive는 지원되는 관리 직접 명령입니다.

기본 NXT 직접 명령 프로토콜은 NXT LCD에 그리거나 버튼을 읽을 수 없습니다. 해당 NXT-G/ROBOTC 기능은 별도로 설치된 NXT 상주 브리지 프로그램이 필요합니다. 이들은 의도적으로 이 서버에서 노출되지 않습니다.

모터 위치 지정 의미론

NXT 엔코더 카운트는 모터 샤프트의 각도(degree)이지, 로봇 방향의 각도나 선형 밀리미터가 아닙니다. 물리적 단위가 필요하면 기어비, 바퀴 둘레, 바퀴 미끄러짐은 로봇 동작(behavior)에서 처리해야 합니다.

절대 0점은 NXT 펌웨어의 프로그램 상대 회전 카운터가 유지합니다. 이것은 홈 센서가 아니며 영구적이지 않습니다. 브릭의 전원을 껐다 켜거나 .rxe 프로그램을 시작/중지하면 기준점이 무효화됩니다. 절대 대상에 의존하기 전에 터치 센서에 대해 홈을 잡고 zero_motor_position을 다시 호출하세요.

그룹 명령은 하나의 컨트롤러 잠금 안에서 연속적인 USB 패킷을 사용하여 모터를 시작합니다. MCP/LLM 왕복 지연(skew)을 피하고 모든 엔코더를 함께 모니터링하지만, 하드 실시간 또는 기계적 위상 고정이 아닙니다. 두 바퀴 로봇의 경우 이는 일반적인 주행에 적합합니다. 정밀 동기화는 NXT 상주 제어 프로그램이 필요할 수 있습니다.

하드웨어 보고 제한

NXT 펌웨어는 모든 포트의 구성된 상태를 보고하지만, 유휴 모터가 물리적으로 연결되어 있는지 안전하게 알 수는 없습니다. 따라서 전체 브릭 쿼리는 모터 존재를 주장하지 않고 모든 A/B/C 펌웨어 상태를 보고합니다. read_sensor 또는 센서 기반 명령으로 이미 구성된 센서 포트는 유형화된 값을 표시하고, 다른 센서 포트는 원시 펌웨어 상태를 표시합니다. 원시 상태를 쿼리해도 포트를 재구성하거나 하드웨어를 잠시 활성화하지 않습니다.

.rxe 프로그램이 동일한 포트를 제어하는 동안 직접 MCP 모터 명령을 사용하지 마세요.

MCP를 통한 PC 측 Python 동작

기본 NXT는 Python을 실행하지 않습니다. 이 서버는 대신 제한된 Python 동작을 PC에 저장하고 실행할 수 있습니다. 모든 로봇 작업은 여전히 컨트롤러 경계를 건너므로 스크립트는 USB를 열거나 NXT-Python 센서를 인스턴스화하거나 자체 폴링 루프를 구현하지 않습니다.

예시 동작:

def run(robot):
    robot.configure_sensor(1, "touch")

    for _ in range(5):
        robot.motor_until("C", 20, 1, "pressed")
        robot.motor_until("C", -20, 1, "released")

    robot.play_tone(440, 500)
    return "completed 5 touch cycles"

동일한 예시는 behaviors/touch_cycle.py로 포함되어 있습니다. 다음 MCP 도구를 사용하세요:

validate_behavior(source)
submit_behavior(name, source)
list_behaviors()
get_behavior(name)
run_behavior(name, timeout_seconds=120)

스크립트에서 볼 수 있는 robot 인터페이스에는 다음이 포함됩니다:

configure_sensor(port, sensor_type)
read_sensor(port, sensor_type)
read_sensor_raw(port, sensor_type=None)
zero_sensor_reference(port, sensor_type)
read_sensor_relative(port, sensor_type)
wait_sensor(port, sensor_type, condition, ...)
sensor_stream(port, sensor_type, ...)
log_start(channels, interval_ms=100, duration_seconds=10)
log_status(job_id)
log_stop(job_id)
log_export(job_id)
motor_until(port, power, sensor_port, condition, sensor_type="touch", ...)
motor_for_ticks(port, power, ticks, ...)
motor_position(port)
zero_motor_position(port)
motor_to(port, target_degrees, power=20, ...)
run_motor(port, power, regulated=True)
drive_sync(left_port, right_port, power, turn_ratio=0)
wait_motors(ports, ...)
stop_motor(port, brake=False)
run_motors(ports, powers, regulated=True)
stop_motors(ports, brake=False)
motors_relative(ports, powers, degrees, ...)
motors_absolute(ports, powers, target_degrees, ...)
motors_until(ports, powers, sensor_port, condition, ...)
state(format="text")
play_tone(frequency_hz=440, duration_ms=500)
play_sound_file(name, loop=False)
stop_sound()
sleep(seconds)

임포트, 클래스, 예외 처리, 비공개 속성 접근, 문서화된 로봇 메서드 및 기본 내장 함수 외부의 호출은 거부됩니다. 스크립트는 64KiB로 제한되며 한 번에 하나만 실행할 수 있고, run_behavior는 1–300초 데드라인을 허용합니다. 스크립트가 끝나거나 예외를 발생시키면 모든 모터가 정지됩니다.

이 검증은 로봇 인터페이스 외부에 대한 우발적 접근을 방지하기 위한 것입니다. 악성 코드를 위한 보안 샌드박스가 아닙니다. 신뢰할 수 있는 로컬 사용자에게만 MCP 접근을 허용하세요. 서버 시작 전에 NXT_BEHAVIOR_DIR을 설정하여 서버 작업 디렉터리 아래의 기본 behaviors 디렉터리가 아닌 다른 곳에 동작을 저장하세요.

컨트롤러를 직접 임포트하지 않고 여전히 MCP stdio를 사용하는 명령줄 데모의 경우:

.\.venv\Scripts\python.exe scripts\mcp-behavior-client.py list
.\.venv\Scripts\python.exe scripts\mcp-behavior-client.py submit touch_cycle behaviors\touch_cycle.py
.\.venv\Scripts\python.exe scripts\mcp-behavior-client.py run touch_cycle --timeout 120

마지막 명령은 물리적 움직임을 수행합니다. 클라이언트는 MCP 도구만 호출합니다. MCP 서버는 동작을 로드하고 모든 NXT 통신을 소유합니다.

브릭 없이 테스트

$env:PYTHONPATH = "src"
py -3.11 -m pytest