한
← 기술 문서

AI 에이전트로 게임 조작하기 (MCP)

Claude Code 등 MCP 클라이언트를 실행 중인 게임에 연결해 상태를 읽고, 스크린샷을 찍고, 키를 누르고, 메뉴를 조작하고, 메모리를 읽거나 쓸 수 있습니다.

업데이트 2026-10-21

Marchwind 64에는 디버그 인터페이스가 내장되어 있습니다. 옵션에서 켜면 게임이 이 컴퓨터에 포트를 엽니다. 소스 저장소에 있는 MCP 서버가 이 포트에 연결해, Claude Code, Codex, Cursor처럼 Model Context Protocol을 지원하는 클라이언트에 게임을 도구 모음으로 제공합니다.

연결하면 에이전트는 다음을 할 수 있습니다.

  • 게임이 지금 무엇을 하고 있는지 확인: 타이틀, 대사, 인터미션 화면, 전투 전 화면, 설정창
  • 스크린샷 촬영과 MP4 클립 녹화
  • 플레이어처럼 키 입력, 또는 네이티브 화면의 버튼과 텍스트 입력란 직접 조작
  • 언어, 이미지 모드, 규칙, 인터페이스 크기 변경
  • 디버깅을 위한 게임 메모리 읽기와 쓰기

저도 이 방법으로 게임을 테스트합니다. 에이전트가 장면을 플레이하고, 버그를 재현하고, 번역된 레이아웃을 확인합니다. 여러분도 같은 방식으로 플레이를 스크립트로 자동화하거나, 영상을 녹화하거나, 겪은 문제를 에이전트에게 조사시킬 수 있습니다.

필요한 것

  • Windows, macOS, Linux 또는 Steam Deck용 게임

  • Python 3. 시스템에 들어 있는 것으로 충분하며 추가 패키지는 필요 없습니다. Windows에서는 python.org에서 설치하며, 명령은 python입니다.

  • MCP 서버 스크립트. 소스 저장소에 있습니다. 클론만 하면 되고 빌드할 것은 없습니다.

    git clone https://github.com/dyzz/srw64-recomp.git

    사용하는 파일은 tools/recomp/debug/mcp_server.py와 같은 폴더의 session.py입니다.

  • MCP를 지원하는 AI 클라이언트

1. 게임에서 디버그 인터페이스 켜기

옵션 → 정보를 열고 **AI 디버그 인터페이스(MCP)**를 켜기로 설정합니다. 다시 시작할 필요 없이 바로 적용됩니다. 이 설정은 저장되며, 게임을 시작할 때마다 화면 위쪽에 아직 켜져 있다는 알림이 표시됩니다. 다 쓰고 나면 같은 곳에서 끄세요. 열려 있던 연결은 즉시 끊어집니다.

켜져 있는 동안 이 항목에는 게임이 연결을 기다리는 주소와 이번 실행의 폴더가 표시되며, 전체 경로를 복사하는 실행 폴더 경로 복사 버튼이 있습니다.

게임은 이 컴퓨터에서만(127.0.0.1) 포트를 열고, 실행 폴더에 포트 번호와 무작위 토큰이 담긴 debug.json을 씁니다. 클라이언트는 다른 무엇보다 먼저 이 토큰을 제시해야 하며, 이 파일은 사용자 본인 계정만 읽을 수 있습니다. 게임을 종료하거나 스위치를 끄면 파일은 삭제됩니다.

실행할 때 --debug로 켤 수도 있습니다 (그 실행에만 적용)
  • macOS: /Applications/Marchwind64.app/Contents/MacOS/srw64-gfx-host --play --rom ~/Games/srw64.z64 --debug (.z64, .v64, .n64 모두 사용 가능)
  • Windows: 압축을 푼 폴더에서 Marchwind64.cmd --debug 실행
  • Linux: ./marchwind64.sh --debug
  • Steam Deck: Steam에서 게임의 실행 옵션을 %command% --debug로 설정

이렇게 켜면 옵션의 스위치가 켜기로 표시되며, 그 실행에서는 끌 수 없습니다.

시스템별 실행 폴더:

시스템 실행 폴더
Windows %LOCALAPPDATA%\SRW64Recomp\sessions\<session>\run\
macOS ~/Library/Application Support/SRW64Recomp/sessions/<session>/run/
Linux / Steam Deck ~/.local/share/srw64-recomp/sessions/<session>/run/

2. 클라이언트에 MCP 서버 추가하기

MCP 서버는 표준 입출력으로 통신하는 Python 스크립트입니다.

Claude Code:

claude mcp add srw64 -- python3 /path/to/srw64-recomp/tools/recomp/debug/mcp_server.py

다른 클라이언트는 대부분 다음과 같은 JSON을 사용합니다. 파일 위치와 정확한 최상위 키는 클라이언트 문서를 확인하세요.

{
  "mcpServers": {
    "srw64": {
      "command": "python3",
      "args": ["/path/to/srw64-recomp/tools/recomp/debug/mcp_server.py"]
    }
  }
}

Windows에서는 python3 대신 python을 쓰고, 경로는 C:\\path\\to\\srw64-recomp\\tools\\recomp\\debug\\mcp_server.py처럼 적습니다 (JSON에서는 백슬래시를 두 번 씁니다).

이제 클라이언트에 이름이 srw64_로 시작하는 도구들이 표시될 것입니다.

3. 연결하고 작업 시작하기

에이전트에게 연결하라고 말하기만 하면 됩니다. 경로는 필요 없습니다.

srw64_attach로 게임에 연결한 다음, 스크린샷을 찍고 지금 어느 화면인지 알려 줘.

인수 없이 호출하면 srw64_attach는 사용자 폴더에서 디버그 인터페이스가 켜진 게임을 찾아, 응답하는 것 중 가장 최근 것에 연결합니다. 게임이 여러 개 실행 중이거나 특정 게임에 연결하려면, 실행 폴더 경로 복사로 얻은 경로를 run 인수로 넘기세요.

그다음에는 평소 말투로 작업을 맡기면 됩니다.

  • “메인 메뉴가 나올 때까지 기다렸다가 새 게임을 시작하고, 첫 선택지까지 빨리 넘겨 줘.”
  • “언어를 영어로 바꾸고 같은 화면의 중국어판 스크린샷과 비교해 줘. 넘치는 텍스트가 있어?”
  • “10초 동안 녹화해 줘. 이 전투 애니메이션이 어디서 끊기는지 보고 싶어.”
  • “대사가 멈췄어. 상태와 최근 이벤트 로그를 읽고 어느 스크립트 명령에서 멈췄는지 알려 줘.”

에이전트는 보통 srw64_status와 스크린샷을 읽어 현재 위치를 파악한 뒤, 지연 시간을 짐작하는 대신 srw64_wait로 조건이 충족될 때까지 기다립니다.

도구

도구 기능
srw64_attach 실행 중인 게임에 연결합니다. 인수가 없으면 가장 최근 게임을 찾고, 실행 폴더를 run으로 넘기면 그 게임을 고릅니다.
srw64_launch 소스에서 빌드해 격리된 개발 세션을 시작합니다 (전체 빌드 환경이 필요합니다. 아래 참고).
srw64_status 현재 상태: 프레임 수, 창, 언어, 이미지 모드, 규칙, 타이틀과 오프닝, 대사 (페이지, 글자 크기, 속도, 빨리 넘기기), 네이티브 화면, 알림, 누르고 있는 키.
srw64_screenshot 다음 프레임을 네이티브 오버레이와 함께 캡처해 이미지로 반환합니다. 설정창 등 다른 창도 캡처할 수 있습니다.
srw64_record 앞으로 몇 초를 MP4로 녹화하고 파일 경로를 반환합니다.
srw64_record_start / srw64_record_stop 끝을 정하지 않은 녹화를 시작하고 멈춥니다.
srw64_wait 조건이 충족될 때까지 기다립니다: 프레임 수, 대사 표시, 화면 열림, 메인 메뉴, 대사 속 특정 텍스트, 이벤트 로그 속 특정 종류의 이벤트.
srw64_events 이벤트 로그를 읽습니다 (대사, 오프닝, 규칙, 설정, 인터미션 화면, 스크립트 등).
srw64_keys 게임 키보드. 플레이어가 무엇을 할당했든 항상 클래식 배치입니다: Z = A, X = B, Enter = START, 방향키, Q/E = L/R, I/K = C-위/아래, WASD = 스틱. 빨리 넘기기용 e+z처럼 키 조합과 누르는 시간을 받습니다.
srw64_pad Steam Deck 버튼 이름을 쓰는 가상 컨트롤러로, 기본 할당대로 동작합니다 (View로 설정 열기 등).
srw64_buttons 키보드 계층을 거치지 않고 N64 컨트롤러 버튼을 직접 누릅니다.
srw64_ui_tree 네이티브 화면 (이름 입력 화면, 설정창, 메뉴 막대)의 컨트롤을 위치와 텍스트와 함께 나열합니다.
srw64_click / srw64_type / srw64_ui_key 텍스트나 위치로 컨트롤을 클릭하고, 텍스트 입력란에 입력하고 (입력기 조합 포함), 인터페이스에 키를 보냅니다.
srw64_menu 경로로 메뉴 막대 항목을 누르거나 메뉴를 나열합니다.
srw64_window 창 크기를 바꾸거나, 앞으로 가져오거나, 닫습니다.
srw64_settings 규칙, 언어, 이미지 모드, 인터페이스 크기, 화면 비율, 각 화면의 원본/모던 모드를 직접 설정합니다.
srw64_mini_stage_load 컴파일된 미니 스테이지 이미지를 불러와 진입합니다. 미니 스테이지를 참고하세요.
srw64_viewer_start 전투 뷰어에서 고른 전투 애니메이션을 재생합니다.
srw64_game_over / srw64_victory 스테이지 스크립트의 패배·클리어 명령과 같은 방식으로 현재 스테이지를 GAME OVER로 끝내거나 승리합니다 (GAME OVER 화면과 재도전, 결과와 종료 이벤트는 게임 본래의 것입니다). 아군 페이즈에 전술맵이 대기 상태이고 실행 중인 이벤트가 없을 때만 동작하며, 그렇지 않으면 이유를 알려 줍니다.
srw64_memory / srw64_memory_write 게임 메모리를 16진수로 읽거나 씁니다. 쓰기는 한 번에 4096바이트까지입니다.
srw64_quit 게임을 정상 종료하고 실행 보고서를 반환합니다.

도구가 실패하면 오류 결과를 반환하며, MCP 서버는 계속 실행됩니다.

알아 둘 점

  • 실제 게임과 실제 세이브입니다. 에이전트는 여러분이 플레이하는 게임에 평소 세이브와 설정 그대로 연결하므로, 에이전트가 저장하거나 설정을 바꾸면 실제로 바뀝니다. 안전하게 실험하려면 먼저 사용자 폴더의 saves/를 백업하거나, --user-dir로 별도 폴더를 지정하고 필요한 세이브를 복사해 넣으세요.
  • srw64_memory_write는 게임을 망가뜨릴 수 있습니다. 게임 모르게 메모리를 바꾸기 때문입니다. 무엇을 하는지 알 때만 사용하세요.
  • srw64_game_over와 srw64_victory는 실제로 스테이지를 끝냅니다. 자신의 게임에서 승리하면 저장할 수 있는 인터미션으로 넘어가고, GAME OVER도 실제로 일어납니다. 테스트에는 별도의 --user-dir를 사용하세요.
  • 인터페이스는 로컬 전용입니다. 게임은 127.0.0.1에서 연결을 기다리므로 네트워크의 다른 기기는 접근할 수 없고, 이 컴퓨터의 다른 프로그램도 debug.json의 토큰이 필요합니다. 이 파일은 공유하지 마세요. 원격으로 쓰려면 ssh 포워딩을 거칩니다 (아래 참고).
  • srw64_quit는 게임을 닫습니다. 연결만 끊고 계속 플레이하려면 대신 옵션 → 정보에서 스위치를 끄세요.
  • 다 쓰면 스위치를 끄세요. 설정이 저장된 채로 남으며, 시작할 때 표시되는 알림도 그 때문입니다.

Steam Deck에 연결하기

컴퓨터에서 Deck으로 ssh 접속이 가능해야 하고 (예: ~/.ssh/config에 Deck이라는 호스트), Deck의 게임에서 옵션 → 정보의 디버그 인터페이스가 켜져 있어야 합니다 (또는 위처럼 --debug로 게임을 시작). 컴퓨터의 저장소에서 다음을 실행합니다.

python3 tools/release/linux/attach.py --host Deck

Deck에서 실행 중인 게임을 찾아, ssh -L로 포트를 컴퓨터로 포워딩하고 현재 세션으로 설정합니다. 그러면 에이전트가 인수 없이 srw64_attach를 호출할 수 있습니다. 스크린샷, 녹화, 이벤트 로그는 게임이 Deck에 쓰는 파일이며, 같은 연결로 자동으로 가져옵니다.

attach.py --start는 ssh로 --debug를 붙여 게임을 시작합니다. --data-dir '~/srw64-debug'를 추가하면 별도의 데이터 폴더를 씁니다. ROM과 HD 팩은 링크하고 세이브와 설정은 복사하므로, 자신의 세이브는 그대로 남습니다.

Android

Android에서도 옵션 → 정보에서 켭니다. 휴대폰은 adb를 통해 컴퓨터와 연결됩니다. 휴대폰의 개발자 옵션에서 USB 디버깅 (또는 무선 디버깅)을 켜고 adb로 연결한 다음, 저장소에서 다음을 실행합니다.

python3 tools/release/android/attach.py --no-start

adb forward로 게임의 인터페이스를 컴퓨터로 포워딩하고 현재 세션으로 설정합니다. 그다음 평소처럼 srw64_attach를 호출하세요. 스크린샷, 녹화, 이벤트 로그도 같은 연결로 가져옵니다. Android에서는 토큰을 쓰지 않으며, 컴퓨터는 adb 포워딩을 통해 인터페이스에 접근합니다.

개발자용: 소스에서 시작하기

전체 로컬 빌드 환경이 있으면 (저장소의 빌드 문서 참고), srw64_launch가 필요에 따라 빌드하고 별도의 디버그 세션을 시작합니다. 실행 폴더는 저장소의 build/recomp/debug/ 아래에 있으며 플레이 세이브는 건드리지 않습니다. 시작할 때 언어, 이미지 모드, 규칙, 세이브, 미니 스테이지를 지정할 수도 있습니다. 세션은 MCP 서버가 종료될 때 끝납니다.

나머지 내용은 저장소의 docs/guide/debug-interface.md에 있습니다: srw64ctl.py 명령줄, Python 스크립트 인터페이스, 인터페이스가 접근할 수 있는 범위.