12.7k 스타 오픈소스의 기여자가 되다

3D에 관심을 가지다

최근 들어 3D 모델링과 실시간 렌더링 분야에 관심이 생겼다. 그러던 중, Claude AI와 Blender(3D툴)를 연결할 수 있는 MCP(Model Context Protocol) 프로젝트를 발견했다.

"AI가 Blender를 직접 제어할 수 있다면" 하는 궁금함이 생겼고 직접 설치해서 사용해보기로 마음먹었다.

MCP와 Blender를 연결하다가 생긴 문제

MCP 서버(blender-mcp)를 설치하고 Claude와 연결을 시도했다. 하지만 예상치 못한 상황이 발생했다. 연결하자마자 에러가 터지며 서버가 죽는 것이었다.

이렇게 큰 오픈소스 프로젝트에서 이런 오류가 날 리가 있나? 아마 내가 설정을 잘못했겠지.. 처음에는 이렇게 생각했다.

하지만 로그를 확인하면서 단순한 설정 문제가 아니란 사실을 알게 되었다.

로그를 열어본 결과

로그에는 다음과 같은 오류를 볼수 있었다.

TypeError: FastMCP.__init__() got an unexpected keyword argument 'description'

코드를 열어보니 Python으로 작성되어 있었고, FastMCP 클래스 생성자에 description이라는 인자가 전달되고 있었다. 문제는 최신 버전의 FastMCP 라이브러리에서 이 인자를 더 이상 지원하지 않는다는 점이었다. 공식 문서를 확인하니 정말로 description 파라미터가 사라진 상태였다.

*FastMCP란?

FastMCP는 MCP 서버를 빠르게 구축할 수 있도록 도와주는 Python 기반 프레임워크로 AI와 애플리케이션 간의 통신을 쉽게 설정할 수 있게 해준다.

MCP 서버를 구현할 때 핵심이 되는 클래스를 제공하며 이를 통해 요청을 받고 응답을 처리하는 구조를 간단히 만들 수 있다.

직접 수정해 보기로 함

문제를 확인한 이상 시도해볼 수밖에 없었다. 캐시된 MCP 서버 스크립트를 열어서 description 인자를 삭제했다. 그리고 서버를 재실행해보니 놀랍게도 정상적으로 Blender와 Claude가 연결되었다.

정말 내 문제가 맞았을까? 이슈 뒤적뒤적

이 정도로 간단한 문제라면 다른 사람들도 이미 보고했을 것. GitHub 이슈 탭을 뒤져봤지만 관련된 오류 보고는 없었다. 대신 AWS MCP 서버에서도 비슷한 문제(version 인자 오류)가 보고되고 있는 것을 발견했다. "나만 겪는 게 아니구나" 라는 확신이 들었다.

PR을 올려도 되나...

문제를 해결했다고 해서 바로 PR을 올리기에는 망설여졌다.

• 단순히 한 줄을 지우는 정도의 수정인데 이런 기여가 의미가 있을까?
• 혹시 내가 잘못 이해한 것이라면 어떡하지?

막상 PR을 올리자니 오픈소스에 기여해본 적이 거의 없었기에 (쓸데없는) 걱정이 앞섰다. 그래서 나는 오픈소스에 기여한 경험이 많은, 내가 아는 천재 개발자에게 조심스럽게 물어봤다.

"오픈소스는 누구나 기여할 수 있는 공간이고, 버그를 발견했다면 수정하는 게 맞다"

..오.. 이런 답을 들었다. (솔직히 이분 덕에 용기를 얻었다.)

실제로 저장소 README에도 누구나 자유롭게 기여해달라는 안내가 있었다.

그 말을 믿고 PR을 올려보기로 했다.

테스트

수정을 마친 후 아래와 같은 방식으로 테스트를 진행했다.

1. 로컬에서 python src/blender_mcp/server.py를 직접 실행해 서버가 정상적으로 뜨는지 확인했다.

2. Claude AI와 Blender를 실제로 연결해 기존 오류가 재발하지 않는지 검증했다.

3. 로그에서 Successfully connected to Blender on startup 메시지가 출력되는 것을 확인했다.

그리고 PR 생성

FastMCP 공식 문서를 재확인해 description 인자가 더 이상 지원되지 않는 사실을 명확히 파악했다. 공식문서 첨부와 왜 제거를 했는지에 대한 내용을 명확히 작성했다.

* PR 내용

---

마무리

이렇게 해서 12.7k 스타를 가진 오픈소스 프로젝트에 첫 기여를 하게 되었다.
코드 한줄로 대형 오픈소스의 기여자가 될수 있다니 .. 아주 짜릿하지 않은가 ^^. 찾아보니 총 12명의 기여자 중에 내가 유일한 한국인인듯 했다.

애걔.. 단 한 줄. 이라고 생각하는 사람도 있을 수 있다. 하지만 나는 실제로 내가 겪은 문제를 해결했고, 누군가는 같은 오류로 시간을 허비하지 않게 됐다면 그 자체로 의미 있는 기여라고 생각한다.

이번 경험을 계기로 앞으로도 작은 부분이라도 오픈소스에 기여할 용기를 내보려 한다.