Claude Code에 Blender 공식 MCP 붙이기: 명령 한 줄부터 첫 장면 요약까지

기준: Claude Code 2.1.310, Blender 5.2 LTS(캡처는 5.2.1, 영어 화면, 기본 단축키), Blender Lab MCP 서버·애드온 1.0.3, Claude Code MCP 공식 문서. 2026년 10월에 확인했습니다. 그림은 모두 실제 터미널·Blender 화면과 렌더입니다. 터미널 그림의 저장 경로 한 줄은 가렸습니다.

Claude Code는 터미널에서 일하는 AI 도우미입니다. 파일을 읽고 쓰고, 명령을 실행하고, 그 결과를 다시 봅니다. 여기에 Blender 재단의 Blender Lab이 만든 공식 MCP 서버를 붙이면, 지금 켜 둔 Blender 장면까지 직접 들여다봅니다. 대화창에 "열린 파일 요약해 줘"라고 쓰면 Claude Code가 MCP 도구로 Blender에 물어보고 표로 답합니다.

이 글을 마치면 아래를 할 수 있습니다.

1. claude mcp add 명령으로 Blender 공식 MCP 서버를 등록합니다.
2. 등록 범위(local·project·user)를 골라 씁니다.
3. 등록 상태를 claude mcp list, claude mcp get, /mcp로 확인합니다.
4. Claude Code에게 Blender 파일 요약과 미리보기 렌더를 시킵니다.
5. 연결이 안 되거나 느릴 때 고칠 곳을 찾습니다.

Claude Code 설치가 처음이라면 Claude Code 입문을, Blender 쪽 애드온 설치가 처음이라면 Blender 공식 MCP 설치하기를 먼저 보세요. 이 글은 두 가지가 다 되어 있다고 보고 시작합니다.

1. Claude Code로 Blender를 다루는 두 가지 길

Claude Code가 Blender를 움직이는 길은 둘입니다.

스크립트 길은 Blender와 AI 연결과 Blender 파이썬 자동화에서 다룹니다. 이 글은 MCP 길입니다. 공식 서버에는 두 길을 잇는 도구도 있습니다. 이름 끝이 _for_cli인 도구는 화면 없는 Blender를 따로 띄워 파일을 열고 답합니다. 자세한 도구 목록은 Blender 공식 MCP 도구 26개 따라 써 보기에 있습니다.

2. 준비물

uv가 없으면 PowerShell에 공식 설치 명령을 붙여 넣습니다. 설치가 끝나면 PowerShell 창을 닫고 새로 엽니다.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

3. 서버 소스 받고 미리 설치해 두기

시작 상태: 새 PowerShell 창에서 시작합니다. Git이 설치되어 있어야 합니다.

따라 하기:

1. 공식 위키(Setup)의 위치대로 C 드라이브 바로 아래에 소스를 받습니다.

cd c:\
git clone https://projects.blender.org/lab/blender_mcp.git

2. 받은 폴더의 mcp 폴더로 들어가 부품을 한 번 설치해 둡니다.

cd C:\blender_mcp\mcp
uv sync

받은 폴더는 약 23 MB(파일 4,783개)이고, 그중 약 16 MB가 함께 들어 있는 Blender 매뉴얼과 파이썬 API 문서입니다. uv sync가 부품 약 55 MB를 더 설치합니다. 제 PC에서는 uv sync에 57초, 다시 설치에 80초가 걸렸습니다.

2번을 건너뛰지 마세요. Claude Code는 MCP 서버가 정해진 시간 안에 켜지기를 기다립니다. 처음 실행 때 uv가 부품을 받는 사이에 그 시간이 지나면, Claude Code는 서버를 끄고 "연결 실패"로 처리합니다. 제 PC에서 이 순서를 건너뛰고 바로 등록했더니, 첫 대화에서 Claude Code가 "30초 연결 시간 초과"로 서버에 닿지 못했습니다. 게다가 설치가 반쯤 된 채로 남아, 다음 실행에서도 서버가 바로 끊겼습니다. 이렇게 되면 아래 명령으로 다시 설치하면 고쳐집니다.

cd C:\blender_mcp\mcp
uv sync --reinstall

4. 등록 명령 한 줄

Claude Code에 MCP 서버를 등록하는 공식 문법은 이렇습니다.

claude mcp add [옵션] <이름> -- <실행 명령> [실행 명령의 인자...]

가운데의 --(빼기 두 개)가 중요합니다. -- 앞은 Claude Code가 읽는 옵션이고, -- 뒤는 서버를 켜는 명령으로 그대로 넘어갑니다. 이 구분이 없으면 Claude Code가 서버의 옵션을 자기 옵션으로 잘못 읽습니다. 택배 상자에 비유하면 -- 앞은 송장, 뒤는 상자 안 물건입니다.

공식 위키의 서버 실행 명령(uv --directory C:\blender_mcp\mcp run blender-mcp)을 이 문법에 넣으면 아래가 됩니다. 범위 옵션(-s)은 바로 다음 절에서 고릅니다.

claude mcp add blender-lab -- uv --directory C:\blender_mcp\mcp run blender-mcp

4-1. 범위 고르기

등록할 때 -s(또는 --scope)로 이 서버를 어디서 쓸지 정합니다.

처음에는 Blender 작업 폴더를 하나 만들고 project 범위로 등록하기를 권합니다. Blender를 움직이는 도구가 그 폴더에서만 켜지니, 다른 일을 할 때 Claude Code가 Blender를 건드릴 일이 없습니다. 열쇠를 집 전체가 아니라 작업실 문에만 다는 셈입니다.

4-2. 등록하기

시작 상태: 3절을 마친 뒤, 새 PowerShell 창에서 시작합니다.

따라 하기:

1. 작업 폴더를 만들고 들어갑니다(이름은 아무거나 됩니다).

mkdir C:\blender-work
cd C:\blender-work

2. 아래 명령으로 등록합니다. 서버 이름은 blender-lab으로 했습니다.

claude mcp add -s project blender-lab -- uv --directory C:\blender_mcp\mcp run blender-mcp

3. 등록한 내용을 확인합니다.

claude mcp get blender-lab

그림 1. 등록과 확인. 첫 줄 아래 Added stdio MCP server blender-lab …, 가운데 범위 Project config, 그 아래 상태 Pending approval. 한국어 Windows에서는 역슬래시가 ₩로 보입니다. 저장 경로 한 줄은 가렸습니다 (PowerShell 화면 캡처)

project 범위로 등록하면 폴더에 .mcp.json 파일이 생깁니다. 안에는 이렇게 적힙니다.

{
  "mcpServers": {
    "blender-lab": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "C:\\blender_mcp\\mcp", "run", "blender-mcp"]
    }
  }
}

상태가 Pending approval(승인 대기)인 것은 정상입니다. 폴더 안 설정 파일은 다른 사람이 넣어 둔 것일 수도 있어서, Claude Code는 그 폴더에서 처음 실행할 때 이 서버를 켜도 되는지 묻습니다. 다음 절에서 허락합니다.

어디서든 쓰고 싶다면: -s project를 -s user로 바꿔 등록합니다. 이때는 폴더를 만들 필요가 없고 승인 대기도 없습니다.

4-3. 옵션 순서에서 자주 막히는 곳

서버에 환경 변수를 넘길 때는 -e(또는 --env)를 씁니다. 그런데 -e 바로 뒤에 서버 이름을 쓰면 오류가 납니다.

> claude mcp add -s project -e BLENDER_MCP_PORT=9886 blender-lab -- uv ...
Invalid environment variable format: blender-lab, environment variables should be added as: -e KEY1=value1 -e KEY2=value2

Claude Code가 이름까지 환경 변수로 읽었기 때문입니다. 공식 문서도 --env와 서버 이름 사이에 다른 옵션을 하나 두라고 안내합니다. 아래처럼 -e를 맨 앞에, -s를 그 뒤에 두면 됩니다.

claude mcp add -e BLENDER_MCP_PORT=9886 -s project blender-lab -- uv --directory C:\blender_mcp\mcp run blender-mcp

BLENDER_MCP_PORT는 공식 서버가 Blender에 전화를 걸 포트 번호입니다. 기본값 9876을 쓰면 필요 없습니다. Blender 쪽 포트를 바꿨을 때만 같은 번호로 맞춥니다.

5. 연결 확인

5-1. 첫 실행과 승인

따라 하기:

1. Blender를 켜고 MCP 애드온의 Server is running을 확인합니다.
2. 4-2절의 작업 폴더에서 claude를 실행합니다.
3. 이 폴더의 .mcp.json에 든 서버를 쓸지 묻는 창이 뜨면 blender-lab을 허락합니다.
4. 대화창에 /mcp를 입력합니다. 서버 목록에서 blender-lab이 연결되어 있는지 봅니다. 공식 서버 1.0.3이 내보이는 도구는 26개입니다.

터미널에서는 claude mcp list로도 상태를 봅니다. 목록에는 등록한 모든 서버가 나옵니다. 그 가운데 Blender 줄만 옮기면 이렇습니다(승인 전).

blender-lab: uv --directory C:\blender_mcp\mcp run blender-mcp - ⏸ Pending approval (run `claude` to approve)

"Connected"의 뜻: 승인한 뒤 이 줄이 ✔ Connected로 바뀌어도, 그것은 서버 프로그램이 켜졌다는 뜻입니다. Blender와 이어졌다는 뜻은 아닙니다. 공식 서버는 Blender가 꺼져 있어도 켜지고 도구 26개를 내보입니다. 도구를 실제로 부를 때 비로소 Blender에 전화를 겁니다. Blender가 없으면 이런 답이 돌아옵니다.

Error executing tool get_blendfile_summary_datablocks: Cannot connect to Blender at localhost:9876. Ensure Blender is running with the MCP addon enabled and the server started.

이 문장이 보이면 Blender를 켜고 서버 상태를 확인하면 됩니다. 전화기는 연결됐는데 상대가 전화를 안 받는 상황입니다.

6. 첫 대화: 열린 파일 요약시키기

시작 상태: Blender에서 공식 데모 파일 Scattering Pebbles(pebble_scattering.blend, blender.org 데모 파일 페이지, CC0)를 열어 둡니다. 5-1절에서 연 Claude Code에서 이어 갑니다.

그림 2. 데모 파일을 연 Blender. Claude Code는 이 창의 장면을 MCP로 읽습니다 (Blender 화면 캡처)

따라 하기:

1. Claude Code 대화창에 아래를 보냅니다.

지금 열려 있는 Blender 파일을 요약해 줘. 물체·재질·컬렉션 수와 렌더 엔진을 표로 짧게.

2. 도구 사용 허락을 물으면 무엇을 하는 도구인지 보고 허락합니다. 읽기만 하는 요약 도구는 파일을 바꾸지 않습니다.

실제로 받은 답은 아래와 같습니다(답 글 그대로).

현재 열린 Blender 파일 요약입니다.

| 항목 | 값 |
|---|---|
| 물체(Object) | 12개 |
| 재질(Material) | 2개 |
| 컬렉션(Collection) | 3개 |
| 렌더 엔진 | Cycles |

- 씬은 `Scene` 하나입니다.
- 물체 12개 중 메시는 8개, 카메라는 1개, 조명은 3개입니다.
- 작업 공간은 `General`과 `Compositing`이 있고, 지금은 `General`이 열려 있습니다.

처음에 시도한 코드 실행이 거부되어, 파일 내용을 읽기만 하는 요약 도구로 조회했습니다. 파일은 바꾸지 않았습니다.

마지막 줄을 눈여겨보세요. 이 대화에서는 읽기 도구만 허락해 두었습니다. Claude Code는 먼저 코드 실행 도구(execute_blender_code)를 쓰려다 막히자, 읽기 전용 요약 도구(get_blendfile_summary_datablocks)로 바꿔 답했습니다. 허락하는 도구에 따라 AI가 할 수 있는 일이 정해진다는 것을 보여 주는 장면입니다.

7. 미리보기 렌더 받아 보기

이번에는 그림을 만들게 해 봅니다. 렌더는 Blender가 장면을 계산해 그림으로 뽑는 일입니다.

시작 상태: 6절과 같은 파일에서 이어 갑니다. 데모 파일의 렌더 엔진은 Cycles입니다. 빠르게 보려면 렌더(Render) 탭에서 Render Engine을 EEVEE로 바꿔 둡니다. 엔진 차이는 EEVEE와 Cycles에 있습니다.

따라 하기:

1. Claude Code에 아래를 보냅니다.

지금 열린 Blender 장면을 작은 미리보기 그림으로 렌더해서 preview.png로 저장하고, 저장된 경로를 알려 줘.

2. 렌더 도구(render_thumbnail_to_path)를 쓰겠다고 물으면 허락합니다.
3. 답에 적힌 경로의 그림을 엽니다.

그림 3. Claude Code가 렌더 도구로 만든 그림. 그림은 1920×1080 원래 크기로 나온 결과를 줄인 것입니다 (Blender 렌더, EEVEE)

여기서 두 가지를 알게 됩니다. 실제로 받은 답의 앞부분입니다.

미리보기 렌더는 됐지만, 파일이 요청한 작업 폴더가 아니라 임시 폴더에 저장됐습니다.

Claude Code는 처음 열린 폴더 밖의 파일을 함부로 만지지 않습니다. 그래서 임시 폴더의 그림을 작업 폴더로 옮기는 일은 여러분에게 허락을 구하거나 직접 하라고 안내합니다.

8. 출력이 길 때와 서버가 늦게 켜질 때

MCP 도구가 돌려주는 글이 너무 길면 Claude Code가 경고합니다. 공식 문서 기준으로 도구 출력이 1만 토큰을 넘으면 경고하고, 기본 2만 5천 토큰에서 자릅니다. 토큰은 AI가 글을 세는 단위로, 글자 몇 개 묶음이라고 보면 됩니다. 자세한 뜻은 토큰과 컨텍스트 창에 있습니다.

물체가 수백 개인 장면에서 "모든 물체를 알려 줘"라고 하면 출력이 금방 길어집니다. 공식 Classroom 데모(물체 985개)에서 물체 목록 도구 하나의 결과가 9만 자를 넘었습니다. 그럴 때는 질문을 좁히는 것이 먼저입니다.

연습 문제

1. 작업 폴더에서 claude mcp get blender-lab을 실행해, 범위(Scope)와 상태(Status) 줄을 적어 보세요.
2. Blender를 끈 채로 Claude Code에게 "열린 파일 요약해 줘"라고 시키고, 어떤 오류 문장이 돌아오는지 확인합니다. 그다음 Blender를 켜고 다시 시켜 보세요.
3. Pebble 파일에서 "카메라와 조명의 이름을 표로 알려 줘"라고 시킨 뒤, 아웃라이너와 비교해 답이 맞는지 보세요.

자주 하는 실수와 해결

같은 이름이 두 범위에 있으면 헷갈리기 쉽습니다. 제 PC에서 user 범위에 blender가 있는 상태로 같은 이름을 project 범위에 더 등록했더니, claude mcp get blender가 user 쪽 내용을 보여 줬습니다. 그래서 이 글은 blender-lab이라는 다른 이름을 썼습니다.

한 줄 정리

uv sync로 미리 설치 → claude mcp add -s project blender-lab -- uv --directory C:\blender_mcp\mcp run blender-mcp → 폴더에서 claude 실행해 허락 → 읽기 질문부터. 다음 글 Blender 공식 MCP 도구 26개 따라 써 보기에서는 서버의 도구를 하나씩 불러 봅니다.

함께 읽기

• Claude Code 입문: 설치부터 첫 대화까지, 터미널에서 일하는 AI 코딩 도우미
• Blender 공식 MCP 설치하기
• MCP 서버 연결하기: AI에게 도구를 붙이는 방법
• Blender 공식 MCP 도구 26개 따라 써 보기
• 공식 Blender MCP와 커뮤니티 MCP for Blender 비교
• Blender와 AI 연결: MCP·스크립트로 3D 작업 시키기

참고 자료

• Claude Code Docs, Connect Claude Code to tools via MCP: https://code.claude.com/docs/en/mcp
• Blender Lab, MCP Server: https://www.blender.org/lab/mcp-server/
• Blender Lab, blender_mcp 저장소와 Setup 위키: https://projects.blender.org/lab/blender_mcp , https://projects.blender.org/lab/blender_mcp/wiki/Setup
• uv 설치 안내: https://docs.astral.sh/uv/getting-started/installation/
• Blender 데모 파일(Scattering Pebbles, Classroom, CC0): https://www.blender.org/download/demo-files/
• 그림: PowerShell·Blender 5.2.1 실제 화면과 Blender 렌더(EEVEE). 장면은 Blender 데모 파일 Scattering Pebbles(CC0)