Odoo ↔ Claude MCP 브리지 — 배포 가이드

이 작은 프로젝트는 여러분의 Odoo 인스턴스(via-italia.odoo.com)와 Claude를 이어 주고, 여러분이 인터페이스에서 클릭하지 않아도 제가 Odoo 안의 것을 직접 읽고 쓸 수 있게 합니다 (재고, 청구서, 고객, 지급 독촉 등).

이 프로젝트는 클라우드 호스팅(Render, 시작은 무료)에서 계속 실행됩니다. Claude는 정식 인증(OAuth)으로 연결합니다. 처음 연결할 때는 로그인 페이지가 비밀 토큰을 요청하지만, 이후에는 Claude가 자동으로 연결된 상태를 유지하며 비밀 토큰이 URL에 나타날 일은 없습니다.

Git 명령 줄은 전혀 필요 없습니다. 전부 브라우저 안에서 처리됩니다.

0단계 — 시작하기 전에 필요한 것

• via-italia.odoo.com에서 생성한 Odoo API 키 (내 기본 설정 → 계정 보안 → 새 API 키). 잘 보관해 두고, 3단계에서 그대로 붙여넣으면 됩니다.

• 접근을 보호하기 위한 비밀 토큰 — 지금 하나 생성해 두세요 (다른 곳이 아니라 오직 Render랑만 공유하고, 다른 어디에도 공유하면 안 됩니다):

  • Mac의 경우: Terminal을 열고 openssl rand -hex 24를 입력한 후 결과값을 복사하세요.

  • 그 외의 경우: 대략 40자 길이의 임의 문자를 만들어 주는 아무 암호 생성기나 사용하면 됩니다.

Related MCP server: odoo-mcp-server

1단계 — 이 파일들을 GitHub에 올리기 (Git 없이)

1. github.com에 가서, 무료 계정이 없다면 계정을 하나 만듭니다.

2. New repository를 클릭합니다. 이름은 odoo-mcp-bridge(혹은 원하는 이름)로 하고, 반드시 Public으로 둡니다(계정을 연동하지 않고 Render에 배포하는 조건). 다른 옵션은 체크하지 말고 Create repository를 클릭합니다.

3. 새 빈 저장소의 안내 페이지에서 uploading an existing file을 클릭합니다.

4. 이 폴더에 들어 있는 6개 파일(Dockerfile, proxy.py, oauth_provider.py, requirements.txt, start.sh, README.md)을 업로드 영역에 끌어다 놓습니다.

5. Commit changes를 클릭합니다.

GitHub 저장소 URL을 기록해 두세요. 형식은 https://github.com/VOTRE-COMPTE/odoo-mcp-bridge입니다.

2단계 — Render에서 서비스 만들기

1. render.com에 접속해서 무료 계정을 만듭니다.

2. New + → Web Service를 선택합니다.

3. Public Git Repository를 선택하고, 1단계에서 만든 GitHub 저장소 URL을 붙여넣은 뒤 Connect를 클릭합니다.

4. 서비스 이름: via-italia-odoo-mcp(또는 원하는 이름).

5. Render가 Dockerfile을 자동으로 감지하므로 Docker 모드를 그대로 둡니다.

6. 시작할 때는 인스턴스 유형을 Free로 지정합니다(테스트에 충분합니다).

3단계 — 환경 변수

이 페이지에서 Advanced를 펼쳐 Add Environment Variable을 누르고, 다음 값을 추가하세요.

(ODOO_DB는 필요하지 않습니다. Odoo가 자동으로 감지합니다.)

Create Web Service를 클릭합니다. 첫 배포는 2~3분가량 걸리며, 빌드 로그가 화면에 표시됩니다.

4단계 — 제대로 동작하는지 확인

배포가 Live가 되면 서비스 주소는 https://via-italia-odoo-mcp.onrender.com 형태입니다.

먼저 브라우저에서 https://via-italia-odoo-mcp.onrender.com/healthz를 열어보세요. ok가 보이면 정상입니다.

클로드에 제공할 커넥터 주소는 그냥 이것뿐입니다:

https://via-italia-odoo-mcp.onrender.com/mcp

이 URL에는 비밀 토큰이 전혀 들어 있지 않으므로 마음대로 공유해도 됩니다. 보호는 다음 단계에서 수행됩니다.

5단계 — Claude에 연결하기

Claude에서 Customize → Connectors → "+" → Add custom connector로 이동해, 4단계의 URL을 붙여넣고 Add을 클릭한 다음 Connecter를 클릭합니다.

로그인 페이지가 열리면서 BRIDGE_SECRET(0단계에서 생성한 비밀 토큰)을 요청하면 입력하고 확인합니다. 이후 Claude는 연결된 상태로 유지됩니다. 서비스를 다시 배포하면 메모리에 보관된 세션이 지워지므로 그때만 다시 연결 작업을 하면 됩니다.

그런 다음 Claude와의 대화로 돌아와 연결 확인을 요청해 보세요 (예: "최근 Odoo 견인 목록을 보여줘").

6단계 — 읽기/쓰기로 전환

읽기 작업이 잘 되고 익숙해지면, Render에서 서비스 → Environment로 가서 ODOO_YOLO 값을 read에서 true로 바꾼 뒤 다시 발행합니다(Render는 환경 변수가 바뀌면 자동으로 재배포합니다). 그러면 Claude가 청구서를 만들거나 재고를 갱신하는 등의 실제 쓰기 작업도 할 수 있게 됩니다. — 단, Claude가 Odoo에 실제로 쓰도록 허용하고 싶은 때에만 활성화하세요.

알아두어야 할 제한 사항

• 서버의 Free 요금제는 15분간 트래픽이 없으면 서비스를 대기(睡觉) 상태로 전환합니다. 따라서 일시중지 후 첫 요청은 서비스가 다시 깨어날 때까지 30~60초가 걸릴 수 있습니다. 매일 더 원활하게 쓰려면 유료 플랜(월 약 $7)을 이용하면 이 대기 전환이 제거됩니다.

• 세션(발급된 OAuth 토큰)은 서비스의 메모리에만 보관되며 디스크에 저장되지 않습니다. 그래서 재배포하거나 재시작하면 세션이 지워지며, Claude 쪽에서 "연결"을 다시 해야 합니다. 이때 BRIDGE_SECRET만 다시 입력하면 되고 그 이상은 없습니다.