Blender 공식 MCP 도구 26개 따라 써 보기: 장면 요약·화면 캡처·렌더·문서 검색

기준: Blender 5.2 LTS(캡처는 5.2.1, 영어 화면, 기본 단축키), Blender Lab MCP 서버·애드온 1.0.3, 공식 저장소의 설명서. 2026년 10월에 확인했습니다. 그림은 모두 실제 Blender 화면, 공식 MCP 도구가 돌려준 그림, Blender 렌더입니다.

AI가 Blender에서 할 수 있는 일은 MCP 서버가 건네준 도구로 정해집니다. 도구는 AI 손에 쥐여 준 공구 상자의 공구 하나하나라고 보면 됩니다. Blender Lab의 공식 MCP 서버 1.0.3에는 도구가 26개 있습니다. 공식 홈페이지에는 이 목록이 따로 없고, 저장소 안의 설명 파일에만 있습니다.

이 글에서는 26개를 일곱 갈래로 나누고, 공식 데모 파일 하나를 열어 실제로 불러 봅니다. 결과 화면을 보고 나면 "연결은 했는데 무엇을 시키지?"라는 막막함이 줄어듭니다.

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

1. 공식 MCP 도구 26개를 일곱 갈래로 구분합니다.
2. 파일 요약 도구로 빠진 파일·링크 파일·쓰임새를 점검합니다.
3. 화면 이동·캡처 도구로 AI에게 원하는 물체를 보여 줍니다.
4. 렌더 도구와 문서 검색 도구의 쓰임과 주의점을 알아 둡니다.
5. 코드 실행 도구를 언제 써야 하는지 판단합니다.

연결이 아직이라면 Blender 공식 MCP 설치하기와 Claude Code에 Blender 공식 MCP 붙이기를 먼저 보세요.

시작 전에

준비물: 공식 MCP가 연결된 AI 앱, Server is running 상태의 Blender 5.1 이상.

1. blender.org 데모 파일 페이지에서 Classroom(zip, 약 70 MB)을 받습니다. 데모 페이지에는 Christophe Seux가 만들고 CC0(누구나 자유롭게 쓰는 조건)로 공개한 파일이라고 적혀 있습니다.
2. 압축을 풀고 classroom 폴더 안의 classroom.blend를 File ‣ Open으로 엽니다.
3. 이 파일의 렌더 엔진은 Cycles입니다. 5절의 렌더를 빨리 보려면 렌더(Render) 탭의 Render Engine을 EEVEE로 바꿉니다.

그림 1. Classroom 데모를 연 화면. 물체 985개가 든 교실 장면입니다. 그림은 렌더 엔진을 EEVEE로 바꾼 뒤의 화면입니다 (Blender 화면 캡처)

AI에게 도구를 부르게 하는 법: 보통은 도구 이름을 몰라도 됩니다. "이 파일에서 빠진 그림 파일이 있는지 봐 줘"처럼 하고 싶은 일을 말하면 AI가 알맞은 도구를 고릅니다. 특정 도구를 꼭 쓰게 하고 싶으면 "get_blendfile_summary_missing_files 도구로"처럼 이름을 넣어 말합니다. 아래 표의 "보낼 말 예"는 그대로 써도 됩니다.

1. 도구 지도: 일곱 갈래 26개

이름 끝이 _for_cli인 도구는 화면 없는 Blender를 따로 띄워, 지정한 .blend 파일을 열고 답합니다. 지금 켜 둔 Blender를 건드리지 않고 다른 파일을 살필 때 씁니다. 저장된 파일 내용만 보므로, 켜 둔 Blender에서 저장하지 않은 변경은 반영되지 않습니다. _for_cli가 없는 도구는 지금 켜 둔 Blender에 묻습니다.

도구 목록은 판마다 바뀔 수 있습니다. 이 글은 1.0.3 기준이고, 서버에 직접 붙어 받은 목록도 26개였습니다.

2. 파일 요약 도구: 건강 검진표

파일 요약 도구는 병원의 건강 검진표 같습니다. 파일을 하나하나 열어 보지 않고도 "어디가 비었는지, 무엇이 많은지"를 숫자로 보여 줍니다. 다섯 종류 모두 읽기만 하므로 파일을 바꾸지 않습니다.

시작 상태: 시작 전에 3단계까지 마친 Classroom 파일에서 이어 갑니다.

따라 하기:

1. AI에게 "빠진 외부 파일이 있는지 봐 줘"라고 보냅니다.
2. 돌아온 목록에서 id_type이 Image인 줄의 path를 봅니다.

Classroom에서 받은 결과의 앞부분입니다(경로 앞부분은 줄였습니다).

{
  "missing_files": [
    { "id_type": "Object", "id_name": "DustParticules", "path": "...\\classroom\\blendcache_classroom\\" },
    { "id_type": "Image", "id_name": "base_bareMetal.png", "path": "...\\classroom\\..\\..\\textures\\_baseTextures\\base_bareMetal.png" },
    { "id_type": "Image", "id_name": "base_leather.jpg", "path": "...\\classroom\\..\\..\\textures\\_baseTextures\\base_leather.jpg" }
  ]
}

빠진 그림 파일은 모두 _baseTextures라는 폴더를 가리킵니다. 압축 파일 안의 ReadMe에도 "baseTextures를 textures 폴더에 넣어야 한다"는 안내가 있습니다. 이 도구가 없으면 렌더해 본 뒤에야 분홍색(빠진 그림 표시)을 보고 알아챘을 문제입니다. 남에게 받은 파일을 처음 열었을 때 가장 먼저 부를 만한 도구입니다.

쓰임새 짐작 도구는 이 파일을 Scripting 100점, Geometry Nodes 100점, Modeling 100점(확신도 68), Animation 67점, Rendering 33점으로 봤습니다. 점수는 파일 속 데이터로 짐작한 값이라 정답은 아닙니다. 처음 보는 파일의 성격을 빨리 가늠하는 용도로 쓰세요.

3. 물체 보기 도구: 목록과 상세

Classroom에서 get_objects_summary의 결과는 9만 자가 넘었습니다. 물체가 985개라서입니다. AI 앱은 긴 결과를 자르거나 경고를 냅니다. 큰 장면에서는 "의자만", "조명만"처럼 좁혀 묻는 편이 낫습니다.

따라 하기:

1. AI에게 "coat 1 물체를 자세히 알려 줘"라고 보냅니다.
2. 결과의 modifiers 부분을 봅니다.

{
  "name": "coat 1",
  "type": "MESH",
  "dimensions": [0.853, 0.325, 0.235],
  "parent": "coatRack",
  "modifiers": [
    { "name": "Subsurf",   "type": "SUBSURF",   "show_viewport": true,  "show_render": true },
    { "name": "Solidify",  "type": "SOLIDIFY",  "show_viewport": false, "show_render": true }
  ],
  "materials": ["leatherCoat"]
}

(소수점 아래는 줄였습니다.) Solidify 모디파이어는 뷰포트에서는 꺼져 있고 렌더에서만 켜져 있습니다. 모디파이어는 사진 필터처럼 원본을 그대로 두고 모양을 바꾸는 기능입니다. 이 차이가 7절에서 면 수가 두 배로 달라지는 까닭입니다.

4. 화면 이동·캡처 도구: AI의 눈과 손가락

이 갈래는 AI가 화면을 보고, 원하는 곳으로 화면을 옮기는 도구입니다.

4-1. 물체로 뷰포트 옮기고 그 영역만 찍기

따라 하기:

1. AI에게 "뷰포트를 coat 1 물체로 옮긴 다음, 3D 뷰 영역만 캡처해서 보여 줘"라고 보냅니다.
2. AI가 jump_to_view3d_object_by_name으로 뷰포트를 옮기고, get_screenshot_of_area_as_image로 3D 뷰포트만 찍습니다.

그림 2. 영역 캡처 도구가 돌려준 그림 그대로. 선택된 coat 1(주황 테두리), 카메라 보기에서 User Perspective로 바뀐 보기 (Blender 화면 캡처, 공식 MCP 도구 결과)

그림에서 보듯 이 도구는 물체를 선택하고 보기를 바꿉니다. 파일 데이터는 바꾸지 않지만 화면 상태는 바뀝니다. 다시 카메라 보기로 돌아가려면 숫자패드 0을 누릅니다.

allow_edits라는 선택 칸도 있습니다. 공식 설명에 따르면 이 값을 켜면 숨겨진 물체를 보이게 하거나 꺼진 컬렉션을 켜서라도 물체를 보여 줍니다. 장면을 바꾸는 일이므로 기본값(꺼짐) 그대로 두기를 권합니다.

4-2. 작업 공간 탭 바꾸기

따라 하기:

1. AI에게 "Scripting 탭으로 바꿔 줘"라고 보냅니다.
2. Blender 위쪽 탭이 Scripting으로 바뀌었는지 봅니다.

그림 3. jump_to_tab_by_name으로 Scripting 탭에 온 화면. 위쪽에 강조된 Scripting 탭, 왼쪽 위 텍스트 편집기, 아래 파이썬 콘솔 (Blender 화면 캡처)

jump_to_tab_by_space_type은 탭 이름 대신 편집기 종류로 찾습니다. 예를 들어 "노드 편집기가 큰 탭으로 가 줘"에 맞습니다.

4-3. 창을 그림이나 글로 보기

창 배치 도구는 Classroom 화면에서 창 크기 1600×900, 속성 편집기가 렌더(RENDER) 탭을 보고 있다는 것, 3D 뷰포트가 카메라 보기라는 것 등을 글로 돌려줬습니다. 그림을 읽지 못하는 AI 모델도 화면 구성을 알 수 있게 해 줍니다.

화면 캡처 도구는 1.0.3에서 고쳐졌습니다. 공식 릴리스 기록에 "오래된 화면 캡처 도구 문제를 고쳤다"고 적혀 있으니, 캡처가 이상하면 서버와 애드온을 1.0.3 이상으로 올리세요.

5. 렌더 도구: 무엇이 어디에 저장되나

두 도구 모두 결과를 Blender 임시 폴더 안의 blender_mcp 폴더에 저장합니다. 넘겨준 경로에서는 파일 이름만 씁니다. 저장된 실제 경로는 도구 결과의 filepath에 나오므로, AI에게 "저장된 경로를 알려 줘"라고 함께 시키세요.

따라 하기:

1. 시작 전에 3단계에서 렌더 엔진을 EEVEE로 바꿨는지 확인합니다.
2. AI에게 "지금 설정 그대로 렌더해서 classroom_full.png로 저장하고 경로를 알려 줘"라고 보냅니다.
3. 렌더가 도는 동안 Blender 화면이 멈춘 것처럼 보일 수 있습니다. 끝날 때까지 기다립니다.

그림 4. render_viewport_to_path로 만든 렌더. 이 장면은 Cycles에 맞춰 조명을 짜 둔 파일이라 EEVEE에서는 어둡게 나옵니다 (Blender 렌더, EEVEE)

렌더는 시간이 걸리고 컴퓨터를 무겁게 씁니다. 큰 장면에서는 출력(Output) 탭의 해상도 %를 낮춰 두고 시키세요. 엔진 차이는 EEVEE와 Cycles에 있습니다.

6. 문서 검색 도구: 서버 안의 도서관

공식 서버에는 Blender 사용자 매뉴얼과 파이썬 API 문서가 들어 있습니다. 소스 폴더 약 23 MB 가운데 약 16 MB가 이 문서입니다. 인터넷에 묻지 않고 이 문서에서 찾으니, 지금 버전에 맞는 답을 얻기 쉽습니다. 동네 도서관이 집 안에 있는 셈입니다.

get_python_api_docs는 클래스나 모듈 이름을 받습니다. bpy.types.RenderSettings.resolution_percentage처럼 속성 이름까지 주면 "찾지 못함(found: false)"과 함께 위 단계인 RenderSettings를 보라고 알려 줍니다. 속성 하나를 찾을 때는 search_api_docs가 맞습니다.

문서 검색은 AI가 코드를 쓰기 전에 스스로 부르는 일이 많습니다. 공식 서버가 연결될 때 AI에게 보내는 안내문에도 문서를 먼저 찾아보라는 내용이 들어 있습니다.

7. 코드 실행 도구: 마지막 수단

execute_blender_code는 파이썬 코드를 지금 켜 둔 Blender에서 그대로 실행합니다. 가장 강력하고, 그만큼 위험합니다. 공식 서버가 AI에게 보내는 안내문도 이 도구를 **"마지막 수단(last resort)"**이라고 부르며, 같은 일을 하는 다른 도구가 있으면 그것을 쓰라고 적습니다. blender.org도 이 코드에는 데이터를 지키는 장치가 없다고 경고합니다.

그래도 다른 도구로 안 되는 분석에는 꼭 필요합니다. 공식 설명서의 세 번째 예시가 그런 경우입니다.

따라 하기:

1. AI에게 아래 공식 예시 문장을 보냅니다.

Analyze the scene and list the outliers: objects with highest polygon count but smaller size from the camera point of view.

2. AI가 코드 실행 도구를 쓰겠다고 하면, 코드가 읽기만 하는지(값을 바꾸거나 지우는 줄이 없는지) 보고 허락합니다.

같은 분석(모디파이어를 적용한 뒤의 면 수를 세어 큰 순서로 정렬)을 공식 서버로 실행한 결과입니다.

크기는 1 m도 안 되는 코트가 면 수 1위입니다. 공식 설명서가 꼽은 두 이상치 coat 1과 alphabet이 그대로 위에 올라왔습니다. 공식 설명서는 coat 1이 렌더 기준으로 세면 약 7만 4천 면이 된다고 적습니다. 3절에서 본 렌더에서만 켜진 Solidify 때문입니다. AI의 답에 면 수가 3만 7천인지 7만 4천인지는 AI가 어느 기준으로 셌는지에 달려 있습니다.

execute_blender_code_for_cli는 같은 일을 화면 없는 Blender에서 합니다. .blend 파일 경로와 코드를 함께 받습니다. 공식 설명서에 따르면 화면 없는 쪽은 결과를 나중에 돌려주는 방식(지연 응답)을 받지 않으니, 코드는 한 번에 끝나야 합니다.

연습 문제

1. Classroom 파일에서 AI에게 "빠진 외부 파일이 몇 건인지 세어 줘"라고 시키고, 33건과 같은지 확인합니다.
2. "뷰포트를 alphabet 물체로 옮겨 줘"라고 시킨 뒤, 그 물체가 교실 어디에 있는지 적어 보세요.
3. "매뉴얼에서 Solidify 모디파이어의 Thickness 설명을 찾아 줘"라고 시키고, 답에 나온 매뉴얼 파일 이름을 적어 보세요.

자주 하는 실수와 해결

한 줄 정리

읽기 도구(요약·목록·캡처·문서)부터, 렌더는 저장 위치를 확인하며, 코드 실행은 마지막에. 공식판과 커뮤니티판 MCP가 무엇이 다른지는 공식 Blender MCP와 커뮤니티 MCP for Blender 비교에서 이어집니다.

함께 읽기

• Blender 공식 MCP 설치하기
• Claude Code에 Blender 공식 MCP 붙이기
• 공식 Blender MCP와 커뮤니티 MCP for Blender 비교
• Blender 파이썬 자동화: 반복 작업을 스크립트로
• 빠른 EEVEE, 정확한 Cycles: Blender 렌더 엔진 고르는 법

참고 자료

• Blender Lab, blender_mcp 저장소(readme, readme_tools): https://projects.blender.org/lab/blender_mcp
• Blender Lab, 릴리스 기록: https://projects.blender.org/lab/blender_mcp/releases
• Blender Lab, MCP Server: https://www.blender.org/lab/mcp-server/
• Blender 데모 파일(Classroom, CC0): https://www.blender.org/download/demo-files/
• Blender 5.2 매뉴얼, Simplify: https://docs.blender.org/manual/en/5.2/render/cycles/render_settings/simplify.html
• 단축키: 카메라 보기 숫자패드 0
• 그림: 모두 Blender 5.2.1 실제 화면, 공식 MCP 도구 결과, Blender 렌더(EEVEE). 장면은 Blender 데모 파일 Classroom(CC0)