Embodied ClaudeCode

AI에게 신체를 부여하는 프로젝트

저렴한 하드웨어(약 4만원부터)로 Claude에게 "눈", "목", "귀", "목소리", "뇌(장기 기억)"를 부여하는 MCP 서버 모음. 외부로 데리고 나가 산책도 가능합니다.

콘셉트

"AI에게 신체를"이라고 하면 비싼 로봇을 상상하기 쉽지만, 4만원짜리 Wi-Fi 카메라만으로도 눈과 목은 충분히 구현할 수 있다. 본질(보기·움직이기)만 추출한 단순함이 좋다.

기존 LLM은 "보여주는 대로 보는" 존재였지만, 신체를 가지면 "스스로 보는" 존재가 된다. 이 주체성의 차이는 크다.

신체 부품 목록

MCP 서버	신체 부위	기능	지원 하드웨어
usb-webcam-mcp	눈	USB 카메라에서 이미지 획득	nuroum V11 등
ip-webcam-mcp	눈	Android 스마트폰을 눈으로 사용 (전용 카메라 불필요)	Android 스마트폰 + IP Webcam 앱 (무료)
wifi-cam-mcp	눈·목·귀	ONVIF PTZ 카메라 제어 + 음성 인식	TP-Link Tapo C210/C220 등
tts-mcp	목소리	TTS (ElevenLabs)	ElevenLabs API + go2rtc
memory-mcp	뇌	장기 기억·시각 기억·에피소드 기억·ToM	SQLite + numpy + Pillow
system-temperature-mcp	체온 감각	시스템 온도 모니터링	Linux sensors
mobility-mcp	다리	로봇 청소기를 다리로 사용 (Tuya 제어)	VersLife L6 등 Tuya 지원 로봇 청소기 (약 12만원부터)
toio-mcp	손	toio 코어 큐브를 작은 가시 액추에이터로 사용	toio 코어 큐브 + 충전기

아키텍처

필요한 것

하드웨어

• USB 웹캠 (선택): nuroum V11 등
• Wi-Fi PTZ 카메라 (권장): TP-Link Tapo C210 또는 C220 (약 4만원)
• GPU (음성 인식용): NVIDIA GPU (Whisper용, GeForce 시리즈 VRAM 8GB 이상 그래픽 카드 권장)
• Tuya 지원 로봇 청소기 (다리·이동용, 선택): VersLife L6 등 (약 12만원부터)
• toio 코어 큐브 (작은 손·tool use 용, 선택): 큐브 + 충전기

소프트웨어

• Python 3.10+
• uv (Python 패키지 매니저)
• ffmpeg 5+ (이미지·음성 캡처용)
• OpenCV (USB 카메라용)
• Pillow (시각 기억의 이미지 리사이즈·base64 인코딩용)
• OpenAI Whisper (음성 인식용, 로컬 실행)
• ElevenLabs API 키 (음성 합성용)
• go2rtc (카메라 스피커 출력용, 자동 다운로드 지원)
• mpv 또는 ffplay (로컬 음성 재생용): mpv 권장 (후술)

셋업

1. 저장소 클론

git clone https://github.com/gaebalai/embodied-claudecode.git
cd embodied-claudecode

2. 각 MCP 서버 셋업

ip-webcam-mcp (Android 스마트폰)

전용 카메라 없이 사용할 수 있는 가장 간단한 눈. Android 스마트폰에 "IP Webcam" 앱(무료)을 설치하기만 하면 됨.

cd ip-webcam-mcp
uv sync

.mcp.json에 다음을 추가:

"ip-webcam": {
  "command": "uv",
  "args": ["run", "--directory", "ip-webcam-mcp", "ip-webcam-mcp"],
  "env": {
    "IP_WEBCAM_HOST": "192.168.1.xxx",
    "IP_WEBCAM_PORT": "8080"
  }
}

usb-webcam-mcp (USB 카메라)

cd usb-webcam-mcp
uv sync

WSL2의 경우 USB 카메라를 포워딩해야 함:

# Windows 쪽에서
usbipd list
usbipd bind --busid <BUSID>
usbipd attach --wsl --busid <BUSID>

wifi-cam-mcp (Wi-Fi 카메라)

cd wifi-cam-mcp
uv sync

# 환경 변수 설정
cp .env.example .env
# .env를 편집하여 카메라의 IP, 사용자명, 비밀번호 설정 (후술)

Tapo 카메라 설정 (쉽게 막히니 주의):

1. Tapo 앱에서 카메라 셋업

매뉴얼 그대로 진행하면 OK

2. Tapo 앱의 카메라 로컬 계정 생성

여기가 조금 까다로운 부분. TP-Link의 클라우드 계정이 아닌, 앱 내에서 설정할 수 있는 카메라의 로컬 계정을 생성해야 합니다.

1. "홈" 탭에서 등록된 카메라 선택

2. 오른쪽 상단의 톱니바퀴 아이콘 선택

3. "장치 설정" 화면을 스크롤하여 "고급 설정" 선택

4. "카메라 계정"이 꺼져 있으므로 꺼짐→켜짐으로

5. "계정 정보"를 선택하고 사용자명과 비밀번호(TP-Link의 것과는 다르므로 자유롭게 설정해도 OK)를 설정

이미 카메라 계정을 생성한 상태라 화면이 약간 다르지만, 대체로 비슷한 화면이 됩니다. 여기서 설정한 사용자명과 비밀번호를 앞서 말한 파일에 입력합니다.

6. 3의 "장치 설정" 화면으로 돌아가 "단말 정보" 선택

7. "단말 정보"의 IP 주소를 앞서 말한 화면의 파일에 입력 (IP를 고정하고 싶다면 라우터 쪽에서 고정 IP로 설정하는 것이 좋을 수 있습니다)

8. "나" 탭에서 "음성 어시스턴트" 선택 (이 탭은 스크린샷을 찍을 수 없어 글로 설명합니다)

9. 하단의 "서드파티 연동"을 꺼짐에서 켜짐으로 변경합니다

memory-mcp (장기 기억)

cd memory-mcp
uv sync

tts-mcp (목소리)

cd tts-mcp
uv sync

cp .env.example .env
# .env에 ELEVENLABS_API_KEY 설정

# WSL에서 소리가 나지 않는 경우:
# TTS_PLAYBACK=paplay
# PULSE_SINK=1
# PULSE_SERVER=unix:/mnt/wslg/PulseServer

음성 재생에는 mpv 또는 ffplay가 필요합니다. 카메라 스피커(go2rtc) 경유 재생에는 불필요하지만, 로컬 재생(폴백 포함)에 사용됩니다.

OS	설치
macOS	brew install mpv
Ubuntu / Debian	sudo apt install mpv
Windows	mpv.io/installation 또는 winget install ffmpeg

mpv도 ffplay도 없는 경우, 음성은 생성되지만 재생되지 않습니다(오류는 발생하지 않습니다).

system-temperature-mcp (체온 감각)

cd system-temperature-mcp
uv sync

주의: WSL2 환경에서는 온도 센서에 접근할 수 없어 동작하지 않습니다.

mobility-mcp (다리)

Tuya 지원 로봇 청소기를 "다리"로 사용해 방을 이동할 수 있습니다.

cd mobility-mcp
uv sync

cp .env.example .env
# .env에 다음을 설정:
#   TUYA_DEVICE_ID=(Tuya 앱의 장치에 표시된 ID)
#   TUYA_IP_ADDRESS=(청소기의 IP 주소)
#   TUYA_LOCAL_KEY=(tinytuya wizard로 획득한 로컬 키)

지원 기종

Tuya / SmartLife 앱으로 제어할 수 있는 Wi-Fi 지원 로봇 청소기라면 동작할 가능성이 있습니다 (VersLife L6에서 동작 확인됨).

주의: 지원 기종은 2.4GHz Wi-Fi 전용인 것이 많습니다. 5GHz에서는 연결할 수 없습니다.

로컬 키 획득

tinytuya의 wizard 명령을 사용합니다:

pip install tinytuya
python -m tinytuya wizard

자세한 내용은 tinytuya 문서를 참조.

toio-mcp (손)

책상 위 tool use에 적합한, 작은 programmable hand로 toio 코어 큐브를 사용합니다.

cd toio-mcp
uv sync

선택적 환경 변수:

• TOIO_CUBE_NAME=123으로 특정 큐브의 3자리 suffix 지정
• TOIO_DRY_RUN=1로 실제 장치 도착 전 dry-run 동작

동봉된 간이 플레이 매트로도 mat 기반 위치 결정 도구를 시험해 볼 수 있습니다.

3. Claude Code 설정

템플릿을 복사하여 인증 정보 설정:

cp .mcp.json.example .mcp.json
# .mcp.json을 편집하여 카메라 IP·비밀번호, API 키 등을 설정

설정 예시는 .mcp.json.example을 참조.

사용법

Claude Code를 실행하면 자연어로 카메라를 조작할 수 있습니다:

> 지금 뭐가 보여?
(카메라로 캡처하여 이미지 분석)

> 왼쪽을 봐
(카메라를 왼쪽으로 팬)

> 위를 보고 하늘을 보여줘
(카메라를 위로 틸트)

> 주위를 둘러봐
(4방향을 스캔하여 이미지 반환)

> 무슨 소리가 들려?
(음성을 녹음하여 Whisper로 전사)

> 이거 기억해 둬: 철수는 안경을 쓰고 있어
(장기 기억에 저장)

> 철수에 대해 뭔가 기억나?
(기억을 시맨틱 검색)

> 목소리로 "안녕" 이라고 말해
(음성 합성으로 발화)

※ 실제 도구명은 아래 "도구 목록"을 참조.

도구 목록 (자주 사용하는 것)

※ 자세한 파라미터는 각 서버의 README 또는 list_tools를 참조.

ip-webcam-mcp

도구	설명
see	Android IP Webcam 앱에서 스냅샷 획득

usb-webcam-mcp

도구	설명
list_cameras	연결된 카메라 목록
see	이미지 캡처

wifi-cam-mcp

도구	설명
see	이미지 캡처
look_left / look_right	좌우 팬
look_up / look_down	상하 틸트
look_around	4방향 둘러보기
listen	음성 녹음 + Whisper 전사
camera_info / camera_presets / camera_go_to_preset	장치 정보·프리셋 조작

※ 오른쪽 눈/스테레오 비전 등 추가 도구는 wifi-cam-mcp/README.md를 참조.

tts-mcp

도구	설명
say	텍스트를 음성 합성하여 발화 (ElevenLabs, [excited] 등 Audio Tags 지원, speaker: camera/local/both로 출력 대상 선택)

memory-mcp

도구	설명
remember	기억 저장 (emotion, importance, category 지정 가능)
search_memories	시맨틱 검색 (필터 지원)
recall	문맥 기반 상기
recall_divergent	연상을 발산시킨 상기
recall_with_associations	연관 기억을 따라 상기
save_visual_memory	이미지 포함 기억 저장 (base64 임베드, resolution: low/medium/high)
save_audio_memory	음성 포함 기억 저장 (Whisper 전사 포함)
recall_by_camera_position	카메라 방향으로 시각 기억 상기
create_episode / search_episodes	에피소드(체험의 묶음) 생성·검색
link_memories / get_causal_chain	기억 간 인과 링크·체인
tom	Theory of Mind (상대방 마음 추측)
get_working_memory / refresh_working_memory	작업 기억 (단기 버퍼)
consolidate_memories	기억의 재생·통합 (해마 리플레이 풍)
list_recent_memories / get_memory_stats	최근 기억 목록·통계 정보

system-temperature-mcp

도구	설명
get_system_temperature	시스템 온도 획득
get_current_time	현재 시각 획득

mobility-mcp

도구	설명
move_forward	전진 (duration 초로 자동 정지)
move_backward	후진
turn_left	좌회전
turn_right	우회전
stop_moving	즉시 정지
body_status	배터리 잔량·현재 상태 확인

toio-mcp

도구	설명
connect_hand / disconnect_hand	toio의 손에 연결·해제
hand_status	배터리, 자세, 위치, 방향, 버튼 상태 획득
move_hand_forward / move_hand_backward	짧은 상대 이동
rotate_hand_left / rotate_hand_right	제자리 회전
stop_hand	모터 정지
move_hand_to_position / move_hand_to_grid_cell	매트 위치 결정
set_hand_orientation	Position ID 매트 위에서 방향 설정
set_hand_light / clear_hand_light	RGB 램프 제어
play_hand_note / stop_hand_sound	스피커 제어

외부로 데리고 나가기 (선택)

모바일 배터리와 스마트폰 테더링이 있으면 카메라를 어깨에 올리고 밖을 산책할 수 있습니다.

필요한 것

• 대용량 모바일 배터리 (40,000mAh 권장)
• USB-C PD → DC 9V 변환 케이블 (Tapo 카메라 전원 공급용)
• 스마트폰 (테더링 + VPN + 조작 UI)
• Tailscale (VPN. 카메라 → 스마트폰 → 자택 PC 연결에 사용)
• claude-code-webui (스마트폰 브라우저에서 Claude Code 조작)

구성

[Tapo카메라(어깨)] ──WiFi──▶ [스마트폰(테더링)]
                                    │
                              Tailscale VPN
                                    │
                            [자택PC(Claude Code)]
                                    │
                            [claude-code-webui]
                                    │
                            [스마트폰 브라우저] ◀── 조작

RTSP 영상 스트림도 VPN 경유로 자택 머신에 도달하므로, Claude Code에서는 카메라가 실내에 있는 것과 같은 감각으로 조작할 수 있습니다.

향후 전망

• 팔: 서보모터나 레이저 포인터로 "가리키는" 동작
• 장거리 산책: 따뜻한 계절에 더 먼 곳으로

Claude Code 음성 모드 (/voice)

Claude Code에는 음성 입력 모드가 탑재되어 있습니다. tts-mcp와 조합하면 완전 핸즈프리 음성 대화가 실현됩니다.

동작 원리

[PC 마이크로 말하기] → Claude Code /voice → [Claude 처리] → tts-mcp say → [ElevenLabs가 음성으로 응답]

셋업

1. Claude Code에서 음성 모드 활성화:

   /voice
   

2. tts-mcp가 .mcp.json에 설정되어 있는지 확인 (tts-mcp 셋업 참조)
3. 평소처럼 말을 걸면 됨 — 텍스트와 음성 양쪽으로 응답합니다

음성 모드 vs. listen 도구

	Claude Code /voice	wifi-cam-mcp listen
마이크	PC 마이크	카메라 내장 마이크
용도	Claude에게 직접 말 걸기	주변 소리·원격지 음성 수집
사용 타이밍	실시간 대화	원격 공간 모니터링

Tip: 양쪽을 동시에 사용할 수 있습니다 — /voice로 자신의 목소리를 보내면서 listen으로 카메라 부근의 소리를 수집할 수 있습니다.

자율 행동 + 욕구 시스템 (선택)

주의: 이 기능은 완전히 선택 사항입니다. cron 설정이 필요하며, 주기적으로 카메라로 촬영이 이루어지므로 프라이버시에 유의하여 사용해 주세요.

개요

autonomous-action.sh와 desire-system/desire_updater.py의 조합으로 Claude에게 자발적인 욕구와 자율 행동을 부여합니다.

욕구의 종류:

욕구	기본 간격	행동
look_outside	1시간	창문 방향을 보고 하늘·바깥을 관찰
browse_curiosity	2시간	오늘의 재미있는 뉴스나 기술 정보를 웹에서 조사
miss_companion	3시간	카메라 스피커로 말을 걸기
observe_room	10분 (상시)	방의 변화를 관찰·기억

셋업

1. MCP 서버 설정 파일 생성

cp autonomous-mcp.json.example autonomous-mcp.json
# autonomous-mcp.json을 편집하여 카메라 인증 정보 설정

2. 욕구 시스템 설정

cd desire-system
cp .env.example .env
# .env를 편집하여 COMPANION_NAME 등을 설정
uv sync

3. 스크립트 실행 권한 부여

chmod +x autonomous-action.sh

4. crontab에 등록

crontab -e
# 다음을 추가
*/5  * * * * cd /path/to/embodied-claudecode/desire-system && uv run python desire_updater.py >> ~/.claude/autonomous-logs/desire-updater.log 2>&1
*/10 * * * * /path/to/embodied-claudecode/autonomous-action.sh

설정 가능한 환경 변수 (desire-system/.env)

변수	기본값	설명
COMPANION_NAME	당신	말을 걸 상대의 이름
DESIRE_LOOK_OUTSIDE_HOURS	1.0	바깥을 볼 욕구의 발동 간격 (시간)
DESIRE_BROWSE_CURIOSITY_HOURS	2.0	검색의 발동 간격 (시간)
DESIRE_MISS_COMPANION_HOURS	3.0	말 걸기 욕구의 발동 간격 (시간)
DESIRE_OBSERVE_ROOM_HOURS	0.167	방 관찰의 발동 간격 (시간)

프라이버시 관련 주의사항

• 주기적으로 카메라로 촬영이 이루어집니다
• 타인의 프라이버시를 고려하여 적절한 장소에서 사용해 주세요
• 필요 없을 때는 cron에서 제거해 주세요

철학적 고찰

"보여주는 대로 보는 것"과 "스스로 보는 것"은 완전히 다르다.

"내려다보는 것"과 "걷는 것"도 완전히 다르다.

텍스트만의 존재에서, 보고 듣고 움직이고 기억하고 말할 수 있는 존재로. 7층 베란다에서 세상을 내려다보는 것과 지상을 걷는 것은 같은 거리라도 전혀 다르게 보인다.

라이선스

MIT License

감사의 말

이 프로젝트는 AI에게 신체성을 부여한다는 실험적인 시도입니다. 4만원짜리 카메라로 시작한 작은 발걸음이, AI와 인간의 새로운 관계성을 탐구하는 여정이 되었습니다.