Blender MCP 연결이 안 될 때: 애드온·포트·시간 초과·uv를 확인하는 순서

기준: Blender 5.2 LTS(캡처는 5.2.1, 영어 화면), Blender Lab MCP 애드온·서버 1.0.3, Claude Code 2.1.318과 공식 MCP 문서, Windows 11 PowerShell. 2026년 11월에 확인했습니다. 그림은 모두 실제 Blender 화면과 PowerShell 화면입니다.

Blender MCP는 세 칸짜리 길입니다. AI 앱이 서버를 켜고, 서버가 Blender 안의 애드온에 전화를 걸고, 애드온이 Blender에서 일을 합니다. 연결이 안 될 때는 이 세 칸 가운데 어디가 끊겼는지부터 찾아야 합니다. 수도가 안 나올 때 집 안 밸브, 계량기, 바깥 수도관을 차례로 보는 것과 같습니다.

이 글은 Blender 쪽에서 AI 앱 쪽으로 한 칸씩 확인하는 순서를 정리합니다. 각 칸마다 실제로 낸 오류 화면과 고친 화면을 함께 보입니다.

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

1. 애드온의 상태 줄을 읽고 서버가 켜졌는지 확인합니다. (2절)
2. PowerShell 한 줄로 Blender의 포트가 열렸는지 확인합니다. (3절)
3. AI 앱의 서버 상태를 보고, 시간 초과를 고칩니다. (4·5절)
4. uv가 있는지, 서버가 켜지는 데 얼마나 걸리는지 잽니다. (6절)
5. AI가 돌려준 오류 문장을 읽고 어느 칸 문제인지 고릅니다. (7절)

설치를 아직 안 했다면 Blender 공식 MCP 설치하기를 먼저 따라 하세요.

1. 확인하는 순서 한눈에

앞 칸이 정상이 아니면 뒤 칸은 볼 필요가 없습니다. 1번에서 막혔다면 1번만 고치고 다시 시켜 보세요.

2. Blender 안: 애드온 상태 줄

시작 상태: Blender를 켠 상태에서 시작합니다. 열린 파일은 무엇이든 됩니다.

따라 하기:

1. Edit ‣ Preferences를 눌러 환경설정(Preferences) 창을 엽니다.
2. 왼쪽에서 Add-ons를 누릅니다.
3. 위쪽 검색 칸에 mcp를 넣습니다.
4. MCP 줄 왼쪽의 화살표를 눌러 펼칩니다.
5. 맨 아래 상태 줄을 읽습니다.

상태 줄은 세 가지 가운데 하나로 보입니다.

그림 1. 서버가 꺼진 상태. 아래쪽 Start MCP Bridge Server 단추와 Server is stopped 줄, 가운데 Port 9876. 그림 위쪽의 Missing Add-ons 줄은 MCP 동작과 상관없고, 여러분 화면에는 없을 수 있습니다 (Blender 화면 캡처)

Auto Start가 켜져 있으면 Blender가 켜지고 1초 뒤에 서버가 저절로 켜집니다. 그런데도 Server is stopped라면 켜려다 실패한 것입니다. 실패하면 상태 줄 아래에 경고가 한 줄 더 붙습니다.

가장 흔한 경고는 온라인 접속이 꺼져 있을 때입니다.

그림 2. 온라인 접속이 꺼진 Blender의 MCP 애드온. Server is stopped 아래의 경고 "Online access must be enabled in the system preferences" (Blender 화면 캡처)

이 애드온은 인터넷이 아니라 같은 PC 안의 연결만 씁니다. 그래도 Blender의 규칙상 온라인 접속 설정이 켜져 있어야 서버가 켜집니다.

따라 하기(그림 2의 경고가 보일 때):

1. 환경설정 왼쪽에서 System을 누릅니다.
2. Network 묶음의 Allow Online Access를 켭니다.
3. 다시 Add-ons ‣ MCP로 와서 Start MCP Bridge Server를 누릅니다.
4. 상태 줄이 Server is running으로 바뀌는지 봅니다.

Blender를 바로 가기나 명령으로 켤 때 --offline-mode가 붙어 있어도 같은 경고가 납니다. 그때는 바로 가기의 대상 칸에서 그 옵션을 지웁니다.

애드온이 목록에 아예 없다면 Blender 버전부터 보세요. 공식 애드온은 Blender 5.1 이상에만 설치됩니다(Help ‣ About에서 버전 확인).

3. Blender의 포트: PowerShell 한 줄

시작 상태: 2절에서 Server is running을 확인한 상태에서 이어 갑니다.

애드온이 "켜졌다"고 해도, 정말 그 번호(포트)로 전화를 받는지 한 번 더 확인할 수 있습니다. 포트는 같은 PC 안의 내선 번호라고 보면 됩니다. 공식 애드온의 기본 포트는 9876입니다.

따라 하기:

1. 시작 메뉴에서 PowerShell을 엽니다.
2. 아래 명령을 넣고 Enter를 누릅니다.

Test-NetConnection 127.0.0.1 -Port 9876 -InformationLevel Quiet

3. 마지막 줄이 True면 Blender가 그 포트로 전화를 받고 있습니다. False면 받는 곳이 없습니다.

그림 3. 포트 확인 결과. 그림은 포트를 9877로 바꿔 켠 Blender(True)와 빈 포트 9878(False)을 견준 화면입니다 (터미널 화면 캡처)

127.0.0.1은 "이 PC 자신"을 뜻하는 주소입니다. localhost라고 써도 되지만, 그러면 IPv6 주소로 먼저 시도해서 경고가 한 줄 더 나올 수 있습니다. 결과는 마지막 줄만 보면 됩니다.

포트를 바꿔 쓰는 법과 커뮤니티판 MCP와 겹칠 때 고치는 법은 공식·커뮤니티 비교 글의 포트 절에 있습니다. 포트를 바꿨다면 AI 앱 쪽 서버에도 같은 번호를 알려야 합니다. 공식 서버는 BLENDER_MCP_PORT라는 환경 변수로 번호를 받습니다.

그림 3 아래쪽의 Get-Process blender-mcp는 지금 켜져 있는 MCP 서버 프로그램 목록입니다. AI 앱이 대화를 시작할 때마다 자기 서버를 따로 켜기 때문에 여러 개가 보일 수 있습니다. 그림 3처럼 여러 개가 남아 있어도 새 연결은 됩니다. 정리하고 싶으면 AI 앱을 모두 닫은 뒤 컴퓨터를 다시 시작하는 것이 가장 쉽습니다.

4. AI 앱 쪽: 서버 상태 읽기

시작 상태: 3절에서 True를 확인한 상태에서 이어 갑니다. 아래는 Claude Code 기준입니다. 다른 앱은 4절 끝의 표를 보세요.

따라 하기:

1. PowerShell에서 아래 명령을 넣습니다. blender 자리에는 여러분이 등록한 서버 이름을 넣습니다.

claude mcp get blender

2. Status: 줄을 읽습니다.

알아 둘 점: Connected는 AI 앱과 서버 사이만 이어졌다는 뜻입니다. 서버가 Blender에 전화를 거는 것은 AI가 실제로 도구를 부를 때입니다. 그래서 Blender가 꺼져 있어도 Connected가 나올 수 있습니다. 2·3절을 먼저 확인하는 까닭이 이것입니다.

다른 앱에서 서버 상태를 보는 곳은 아래와 같습니다. 자세한 등록 방법은 앱마다 따로 쓴 글에 있습니다.

5. 시간 초과: 서버가 늦게 켜질 때

시작 상태: 4절에서 Failed to connect와 "timed out"이 보인 경우에 이어 갑니다.

AI 앱은 MCP 서버가 켜지기를 정해진 시간만큼만 기다립니다. Claude Code의 기본값은 30초입니다(공식 문서의 MCP_TIMEOUT). 서버가 그보다 늦게 켜지면 연결 실패로 처리합니다. 식당에서 30분 안에 자리가 안 나면 예약을 취소하는 것과 같습니다.

그림 4는 같은 오류를 일부러 낸 화면입니다. 기다리는 시간을 5초로 줄였더니 실패했고, 90초로 늘렸더니 연결됐습니다.

그림 4. 기다리는 시간에 따라 달라진 결과. 위쪽 5초에서 Failed to connect와 Issue 줄의 timed out after 5000ms, 아래쪽 90초에서 Connected (터미널 화면 캡처)

따라 하기(Claude Code에서 기다리는 시간 늘리기):

1. PowerShell에서 아래 줄을 먼저 실행합니다. 숫자는 밀리초이고, 90000은 90초입니다.

$env:MCP_TIMEOUT = "90000"

2. 같은 창에서 claude를 실행합니다.
3. 대화 중 /mcp에서 Blender 서버가 연결됐는지 봅니다.

이 설정은 그 PowerShell 창 안에서만 유지됩니다. 창을 새로 열면 다시 넣어야 합니다.

다른 앱도 기다리는 시간을 바꾸는 칸이 있습니다. 칸 이름과 기본값이 앱마다 다릅니다.

Codex는 기본값이 10초로 가장 짧습니다. 서버가 켜지는 데 6절처럼 16~26초가 걸리는 PC에서는 Claude Code는 되고 Codex만 실패할 수 있습니다. Codex를 쓴다면 config.toml의 Blender 서버 항목([mcp_servers.blender] 같은 줄 아래)에 startup_timeout_sec = 30을 한 줄 넣어 30초로 늘려 두세요.

시간을 늘리기 전에, 서버가 왜 늦게 켜지는지 6절에서 직접 재 보세요.

6. uv와 서버 시작 시간 재기

시작 상태: 5절과 같은 PowerShell 창에서 이어 갑니다.

공식 서버는 보통 uv라는 도구로 켭니다. uv는 파이썬 프로그램을 필요한 부품과 함께 실행해 주는 도구입니다. 재료를 꺼내 와 차려 주는 보조 요리사라고 보면 됩니다. uv가 없거나 경로를 못 찾으면 서버가 아예 켜지지 않습니다.

따라 하기:

1. uv가 어디 있는지 찾습니다.

where.exe uv
uv --version

2. 경로와 판 번호가 나오면 uv는 있습니다. "찾을 수 없다"는 말이 나오면 uv를 설치하고 PowerShell 창을 새로 엽니다. 설치 명령은 Blender 공식 MCP 설치하기의 5절에 있습니다.
3. 서버가 켜지는 데 걸리는 시간을 잽니다. 폴더 경로는 여러분이 서버를 받아 둔 곳으로 바꿉니다.

Measure-Command { uv --directory C:\blender_mcp\mcp run blender-mcp --help } | Select-Object TotalSeconds

그림 5. uv 위치와 판, 서버 시작 시간. 맨 아래 TotalSeconds 24.0은 서버가 도움말 한 번을 띄우는 데 걸린 초입니다. 그림은 서버를 사용자 폴더 아래에 받아 둔 화면입니다 (터미널 화면 캡처)

--help는 서버를 켜서 사용법만 보이고 끝내는 옵션입니다. 그래서 이 시간은 "서버가 켜지기까지 걸리는 시간"과 거의 같습니다. 제 PC에서는 같은 측정이 16~26초 사이로 매번 달랐습니다. Claude Code의 기본 기다리는 시간 30초에 꽤 가깝습니다. 실제로 제 PC에서는 Claude Code를 켤 때 Blender 서버가 "connection timed out after 30000ms"로 연결되지 않은 적이 있습니다.

처음 실행이 느린 이유와 uv sync로 미리 설치해 두는 법은 Claude Code에 Blender 공식 MCP 붙이기의 3절에 있습니다.

7. AI의 답에 나온 오류 문장 읽기

1~6절이 모두 정상인데도 AI가 일을 못 했다면, AI의 답에 나온 오류 문장을 봅니다. 공식 서버가 돌려주는 문장은 정해져 있어서 어느 칸 문제인지 고르기 쉽습니다.

아래는 Blender가 받지 않는 포트로 서버를 켜 두고 "지금 열린 Blender 장면에 어떤 물체가 있는지 알려 줘"라고 시켰을 때 돌아온 도구 결과입니다.

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

AI는 이 결과를 받고 "Blender에 연결하지 못해 목록을 가져오지 못했다"고 답한 뒤, Blender가 켜졌는지와 애드온 서버를 켰는지 확인하라고 안내했습니다.

마지막 줄은 조금 특별합니다. 공식 서버에는 열린 Blender 창 대신 Blender를 화면 없이 따로 띄워 파일을 읽는 도구도 있습니다(이름이 _for_cli로 끝나는 도구). 이 도구는 Blender 실행 파일의 위치를 BLENDER_PATH라는 환경 변수에서 찾고, 없으면 blender라는 이름으로 찾습니다. Windows에서는 보통 이 이름으로 찾지 못해서 이 오류가 납니다. 열린 Blender로 일하는 것이 목적이라면, AI에게 "열린 Blender에서 해 줘"라고 다시 말하면 됩니다.

애드온은 Blender가 한가할 때 요청을 처리합니다. 렌더가 돌거나 파일 열기 창이 떠 있는 동안에는 요청이 기다립니다. 그래서 무거운 렌더를 걸어 둔 채 다른 일을 시키면 답이 늦게 옵니다.

연습 문제

1. 2절의 상태 줄과 3절의 포트 확인 결과를 적어 보세요. 둘이 맞는지(running이면 True) 확인합니다.
2. Blender를 끈 상태에서 3절의 명령을 실행해 False가 나오는지 보세요. 그다음 Blender를 켜고 다시 실행해 True로 바뀌는지 확인합니다.
3. 6절의 Measure-Command를 세 번 실행해 시간을 적어 보세요. 가장 긴 시간이 여러분 AI 앱의 기다리는 시간보다 짧은지 확인합니다.

자주 하는 실수와 해결

한 줄 정리

Blender 상태 줄(running) → 포트 확인(True) → 앱의 서버 상태(Connected) → 서버 시작 시간과 기다리는 시간 → 오류 문장, 앞 칸부터 하나씩. 연결이 됐다면 Blender MCP 처음 써 볼 질문 10개로 첫 일을 시켜 보세요.

함께 읽기

• Blender 공식 MCP 설치하기
• Claude Code에 Blender 공식 MCP 붙이기
• 공식 Blender MCP와 커뮤니티 MCP for Blender 비교
• AI에게 Blender를 맡기기 전 안전 점검
• MCP 서버 연결하기
• Blender MCP 처음 써 볼 질문 10개
• Blender MCP에 쓸 AI 도구 고르기

참고 자료

• Blender Lab, MCP Server: https://www.blender.org/lab/mcp-server/
• Blender Lab, blender_mcp 저장소: https://projects.blender.org/lab/blender_mcp
• Claude Code MCP 문서(서버 상태, 시간 초과): https://code.claude.com/docs/en/mcp
• Claude Code 환경 변수(MCP_TIMEOUT): https://code.claude.com/docs/en/env-vars
• Blender 5.2 매뉴얼, System 환경설정(온라인 접속): https://docs.blender.org/manual/en/5.2/editors/preferences/system.html
• Blender 5.2 매뉴얼, 명령줄 옵션(--offline-mode): https://docs.blender.org/manual/en/5.2/advanced/command_line/arguments.html
• Microsoft, Test-NetConnection: https://learn.microsoft.com/powershell/module/nettcpip/test-netconnection
• uv 설치 안내: https://docs.astral.sh/uv/getting-started/installation/
• 그림: 모두 Blender 5.2.1 실제 화면과 Windows PowerShell 화면