직접 만든 FX MCP 서버, 이렇게 씁니다

2026-09-19 · 이 맥의 실제 상태 기준(블렌더 5.2 설치됨, 블렌더 안 수신기 애드온 설치됨, 데스크톱 앱에 blender-mcp 등록됨, uv 있음)

결론

MCP 서버는 "AI에게 쥐여주는 리모컨"입니다. 만들고 나면 쓰는 건 세 단계입니다. ① 설정 파일에 리모컨을 한 줄 등록 ② 블렌더를 켜고 수신기(애드온) 켜기 ③ 말로 시키기. 지금 쓰는 blender-mcp도 정확히 이 방식으로 등록돼 있습니다. 새 서버는 옆에 한 줄 더 추가하면 됩니다.

1. 먼저, 걸리는 부분

  1. 블렌더가 켜져 있어야 합니다. 리모컨을 눌러도 TV가 꺼져 있으면 아무 일도 없습니다. 오늘 두 번 확인했는데 둘 다 "블렌더에 연결 못 함"이었습니다. 매번 블렌더를 먼저 켜고 수신기를 켜야 합니다.
  2. 수신기 하나에 리모컨 둘이면 충돌할 수 있습니다. 새 서버도 기존 blender-mcp와 같은 수신기(포트 9876)로 말을 겁니다. 두 서버가 동시에 붙어 있으면 한쪽이 끊길 수 있습니다. 새 서버를 쓸 땐 blender-mcp를 잠시 끄거나, 새 서버가 "명령 보낼 때만 붙었다 떼는" 방식으로 만듭니다.
  3. 코덱스엔 아직 아무것도 등록돼 있지 않습니다. 코덱스 설정 파일에 blender 항목이 없습니다. 클로드와 코덱스 둘 다 쓰려면 각각 등록해야 합니다.
  4. 서버가 죽으면 AI는 "그런 도구 없는데요"라고 합니다. 원인을 AI가 못 찾는 경우가 많아서, 등록 전에 인스펙터(리모컨 시험기)로 먼저 확인하는 습관이 필요합니다.
  5. "직접 만든다"의 실체는 "AI에게 짜게 하고 내가 검수"입니다. 파이썬을 몰라도 되지만, 폴더 만들기·등록·테스트·"그림이 봐줄 만한가" 판정은 Sam이 합니다.

2. 세 조각 중 만드는 건 하나

조각지금 상태할 일
① 블렌더 안 수신기(애드온)이미 설치됨(blender_mcp.py, 5.2)안 만듭니다. 처음엔 그대로 빌려 씁니다. 포트 9876, 명령 이름 execute_code로 파이썬을 받아 실행합니다.
② 밖 MCP 서버(리모컨)없음이걸 만듭니다. 파이썬 파일 하나 + 레시피 폴더. 도구는 처음에 destroy 하나.
③ 등록(리모컨 쥐여주기)blender-mcp만 데스크톱 앱에 등록됨새 서버를 데스크톱 앱·클로드 코드·코덱스에 각각 한 줄 추가.
[클로드 / 코덱스] ──③등록── [② FX MCP 서버: server.py + recipes/]
                                     │  "execute_code" + 레시피 파이썬
                                     ▼ (localhost:9876)
                            [① 블렌더 안 수신기 애드온] → 블렌더가 실행

3. 만드는 순서(AI에게 시키는 말 그대로)

1단계 · 폴더 만들기

mkdir -p ~/Desktop/클로드/blender-fx-mcp/recipes

2단계 · 클로드 코드에 이렇게 시킵니다

프롬프트: "~/Desktop/클로드/blender-fx-mcp 에 FastMCP로 MCP 서버를 만들어줘. uv 프로젝트로. 도구는 destroy 하나만. 인자는 target(오브젝트 이름), impact(충격 위치: left/right/center), pieces(조각 수, 기본 150), material(concrete/glass/wood). 실행하면 recipes/destroy.py를 읽어 인자를 채운 뒤 localhost:9876으로 JSON {"type":"execute_code","params":{"code":...}}을 보내고, 결과로 프레임 5장 PNG 경로 목록을 돌려줘. 소켓은 명령마다 연결하고 끊어. recipes/destroy.py는 블렌더 5.2 기준으로 셀 프랙처 + 리지드바디 + 60프레임 굽기 + 저해상도 렌더까지 하게 짜줘."

AI가 코드를 씁니다. Sam은 파일 두 개가 생겼는지만 봅니다. server.py와 recipes/destroy.py.

3단계 · 리모컨 시험기로 확인

npx @modelcontextprotocol/inspector uv --directory ~/Desktop/클로드/blender-fx-mcp run server.py

브라우저 창이 뜨고 도구 목록에 destroy가 보이면 서버는 정상입니다. 블렌더가 꺼져 있어도 목록까지는 나옵니다.

4. 등록(리모컨 쥐여주기)

클로드 코드(터미널·데스크톱 Code 탭)

claude mcp add -s user blender-fx -- uv --directory ~/Desktop/클로드/blender-fx-mcp run server.py

클로드 데스크톱 앱(채팅)

~/Library/Application Support/Claude/claude_desktop_config.json의 mcpServers 안, 기존 "blender" 옆에 추가:

"blender-fx": {
  "command": "/opt/homebrew/bin/uv",
  "args": ["--directory", "/path/to/blender-fx-mcp", "run", "blender-fx-mcp"]
}

코덱스

~/.codex/config.toml에 추가:

[mcp_servers.blender_fx]
command = "/opt/homebrew/bin/uv"
args = ["--directory", "/path/to/blender-fx-mcp", "run", "blender-fx-mcp"]

등록 후 앱이나 세션을 다시 시작해야 도구가 보입니다. 데스크톱 앱은 Cmd+Q로 완전히 껐다 켭니다.

5. 매일 쓰는 순서

  1. 블렌더 실행(/Applications/Blender.app).
  2. 3D 화면에서 N 키 → 오른쪽 탭 BlenderMCP → Connect to MCP server(또는 Start) 누르기. 이게 수신기 켜기입니다.
  3. 클로드 코드(또는 코덱스) 열기.
  4. 말로 시키기: "Cube를 왼쪽에서 충격 줘서 콘크리트처럼 무너뜨려, 조각 300개"
  5. AI가 destroy를 부르고, 프레임 5장을 보여줍니다. 보고 "더 느리게", "먼지 많이"로 반복합니다.

blender-mcp와 새 서버를 동시에 켜두면 수신기 충돌이 날 수 있습니다. 새 서버 시험 중엔 데스크톱 앱 설정에서 "blender" 항목을 잠시 빼거나, 새 서버가 명령마다 붙었다 떼도록 만들어 두면 대부분 괜찮습니다.

6. 오픈소스로 공개하면 남들은 이렇게 씁니다

GitHub에 올리고 README 첫 줄에 한 줄만 적으면 끝입니다:

claude mcp add -s user blender-fx -- uvx --from git+https://github.com/<계정>/blender-fx-mcp blender-fx-mcp

사용자 쪽 준비물은 블렌더 + blender-mcp 애드온(수신기) + uv 세 가지입니다. 지금 Sam 맥에 이미 다 있습니다.

7. 막혔을 때 보는 순서

증상먼저 볼 것
AI가 "destroy 도구가 없다"고 함인스펙터(3단계)에서 도구가 보이는지. 안 보이면 서버 코드 문제. 보이면 등록 줄 오타나 재시작 안 함.
"블렌더에 연결 못 함"블렌더 켜졌는지, N 패널에서 수신기 켰는지, 포트 9876인지.
도구는 돌았는데 그림이 이상함레시피(recipes/destroy.py) 문제. AI에게 프레임 보여주고 "조각이 안 떨어짐, 리지드바디 확인해" 식으로 넘김.
갑자기 끊김blender-mcp와 새 서버가 동시에 붙었는지. 하나만 남김.