Odoo 19 MCP 서버 (JSON-2 API)

odoo19-mcp-server MCP server

License: Apache-2.0 Python GitHub stars GitHub last commit Awesome MCP Servers

Youtube 튜토리얼 - MCP Server 직접 만들기! Odoo 19 + FastMCP 전체 개발 강의

Odoo 19 MCP 서버, JSON-2 API를 사용하여 연결합니다.

본 프로젝트는 Odoo 19 JSON-2 API 전체 사용 가이드를 기반으로 개발되었습니다.

실행 화면

기술 스택

Python: 3.13
FastMCP: >=3.0.0,<4.0.0
odoo-client-lib: 2.0.1 (JSON-2 API)

아키텍처

flowchart TB
    subgraph Client["MCP Client"]
        CC[Claude Code]
        GC[Gemini CLI]
        MI[MCP Inspector]
    end

    subgraph Server["MCP Server (FastMCP)"]
        R[Resources<br/>odoo://models<br/>odoo://user<br/>odoo://company]
        T[Tools<br/>search_records<br/>create_record<br/>update_record]
        DI[Dependency Injection<br/>get_shared_client]
    end

    subgraph RPC["OdooJsonRpcClient"]
        OL[odoolib<br/>json2/json2s protocol]
    end

    subgraph Odoo["Odoo Server"]
        EP["/jsonrpc endpoint"]
    end

    Client -->|MCP Protocol<br/>stdio/http/sse| Server
    R --> DI
    T --> DI
    DI --> RPC
    RPC -->|HTTP/HTTPS| Odoo

MCP 핵심 개념

리소스(Resources) vs 도구(Tools)

특성	리소스 (Resources)	도구 (Tools)
용도	컨텍스트 정보 제공	작업/동작 수행
트리거	클라이언트 제어 (예: Claude Code)	LLM이 호출 여부 자동 결정
매개변수	없음 (또는 URI 매개변수)	있음 (LLM이 생성해야 함)
비유	직원 핸드북 (배경 지식)	도구 상자 (필요 시 사용)
HTTP 비유	GET (읽기)	POST/PUT/DELETE (작업)

리소스 - 동적 컨텍스트, LLM이 처음에 알고 있는 배경 정보:

odoo://user     → "我是誰"
odoo://company  → "我在哪間公司"
odoo://models   → "有哪些模型可用"

도구 - 필요할 때만 호출하는 작업:

search_records(model="res.partner", domain=[...])  → 搜尋
create_record(model="sale.order", values={...})    → 建立

왜 기본 프롬프트(Default Prompt)를 사용하지 않나요?

방식	기본 프롬프트	리소스
데이터 소스	코드에 하드코딩	Odoo에서 실시간 조회
업데이트 시점	배포 시	연결할 때마다
사용자 변경 시	정보 오류	자동으로 정확함

# ❌ Default Prompt（寫死）
SYSTEM_PROMPT = "當前用戶: Admin"  # 換人登入就錯了

# ✅ Resource（動態）
@mcp.resource("odoo://user")
def get_current_user():
    return client.read("res.users", [uid])  # 即時查詢

결론: 리소스는 정적 텍스트가 아닌 "동적 컨텍스트"입니다.

참고: MCP Resources | MCP Tools

환경 변수

변수	설명	기본값
`ODOO_URL`	Odoo 서버 URL	`http://localhost:8069`
`ODOO_DATABASE`	데이터베이스 이름	-
`ODOO_API_KEY`	API Key 인증	-
`READONLY_MODE`	읽기 전용 모드 (쓰기 작업 금지)	`false`

.env 파일 생성:

cp .env.example .env

설치

pip install -r requirements.txt

실행 방법

개발 모드 (MCP Inspector)

fastmcp dev inspector odoo_mcp_server.py

전송 모드 (Transport)

본 프로젝트는 세 가지 MCP 전송 모드를 지원합니다:

모드	설명	적용 상황
`stdio`	표준 입출력 (기본값)	Claude Desktop, Cursor IDE, 로컬 개발
`http`	HTTP 프로토콜	원격 서비스, n8n, 웹 애플리케이션 통합
`sse`	Server-Sent Events (사용 중단 예정)	이전 버전 클라이언트와의 하위 호환성

stdio vs HTTP/SSE: 연산 위치

두 모드의 핵심 차이는 "누가 MCP 서버를 시작하는가"와 "연산이 어디서 수행되는가"입니다:

stdio 모드 (로컬 연산)

┌─────────────────────────────────────┐
│            你的電腦 💻               │
│                                     │
│  Claude Desktop ──> MCP Server      │
│                     (使用本機算力)   │
└─────────────────────────────────────┘

클라이언트(예: Claude Desktop)가 MCP 서버를 자식 프로세스로 시작
MCP 서버가 내 컴퓨터의 CPU/RAM을 사용
클라이언트 시작/종료와 함께 서버도 시작/종료

HTTP/SSE 모드 (원격 연산)

┌──────────────┐         ┌──────────────────┐
│   你的電腦    │         │     雲端 ☁️       │
│              │         │                  │
│Claude Desktop│ ──網路──>│   MCP Server     │
│  (輕量)      │         │  (使用雲端算力)   │
└──────────────┘         └──────────────────┘

MCP 서버가 클라우드/원격 호스트에서 독립적으로 실행
여러 클라이언트가 동시에 동일한 서버에 연결 가능
팀 공유, n8n 통합, 운영 환경에 적합

모드별 실행

# stdio 模式（預設）
python odoo_mcp_server.py

# HTTP 模式
python odoo_mcp_server.py --transport http --host 0.0.0.0 --port 8000

# SSE 模式（已棄用，建議使用 HTTP）
python odoo_mcp_server.py --transport sse --host 0.0.0.0 --port 8000

클라우드 배포 (HTTP 모드)

Docker Compose 예시:

services:
  odoo-mcp:
    build: .
    ports:
      - "8000:8000"
    environment:
      - ODOO_URL=http://odoo:8069
      - ODOO_DATABASE=odoo19
      - ODOO_API_KEY=your_api_key_here
    command: ["python", "odoo_mcp_server.py", "--transport", "http", "--host", "0.0.0.0", "--port", "8000"]
    restart: unless-stopped

클라이언트 설정(claude)에서 URL 연결 사용:

claude mcp add --transport http odoo-mcp https://your-cloud-server.com:8000/mcp

{
  "mcpServers": {
    "odoo-mcp": {
      "type": "http",
      "url": "https://your-cloud-server.com:8000/mcp"
    }
  }
}

MCP 리소스

URI	설명
`odoo://models`	모든 모델 나열
`odoo://model/{model_name}`	모델 필드 정의 가져오기
`odoo://record/{model_name}/{record_id}`	단일 레코드 가져오기
`odoo://user`	현재 로그인한 사용자 정보
`odoo://company`	현재 사용자의 소속 회사 정보

MCP 도구

도구	설명	읽기 전용
`list_models`	사용 가능한 모델 나열/검색	Yes
`get_fields`	모델 필드 정의 가져오기	Yes
`search_records`	레코드 검색	Yes
`count_records`	레코드 개수 세기	Yes
`read_records`	지정된 ID의 레코드 읽기	Yes
`create_record`	레코드 생성	No
`update_record`	레코드 수정	No
`delete_record`	레코드 삭제 (2차 확인 필요)	No
`execute_method`	모델 메서드 실행	Depends

Claude Code MCP 설정

설정 파일은 ~/.claude.json에 위치합니다:

로컬 실행

claude mcp add odoo-mcp-server -- python odoo_mcp_server.py

{
  "mcpServers": {
    "odoo-mcp-server": {
      "command": "/bin/python",
      "args": [
        "odoo_mcp_server.py"
      ]
    }
  }
}

Docker (host.docker.internal)

Odoo가 로컬에서 실행 중인 경우:

claude mcp add odoo-mcp-server -- docker run -i --rm --add-host=host.docker.internal:host-gateway -e ODOO_URL=http://host.docker.internal:8069 -e ODOO_DATABASE=odoo19 -e ODOO_API_KEY=your_api_key_here odoo-mcp-server

{
  "mcpServers": {
    "odoo-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--add-host=host.docker.internal:host-gateway",
        "-e",
        "ODOO_URL=http://host.docker.internal:8069",
        "-e",
        "ODOO_DATABASE=odoo19",
        "-e",
        "ODOO_API_KEY=your_api_key_here",
        "odoo-mcp-server"
      ]
    }
  }
}

Docker (호스트 네트워크)

호스트 네트워크 모드 사용:

claude mcp add odoo-mcp-server -- docker run -i --rm --network host -e ODOO_URL=http://localhost:8069 -e ODOO_DATABASE=odoo19 -e ODOO_API_KEY=your_api_key_here odoo-mcp-server

{
  "mcpServers": {
    "odoo-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network",
        "host",
        "-e",
        "ODOO_URL=http://localhost:8069",
        "-e",
        "ODOO_DATABASE=odoo19",
        "-e",
        "ODOO_API_KEY=your_api_key_here",
        "odoo-mcp-server"
      ]
    }
  }
}

Docker (원격 Odoo)

claude mcp add odoo-mcp-server -- docker run -i --rm -e ODOO_URL=https://example.com/ -e ODOO_DATABASE=odoo19 -e ODOO_API_KEY=your_api_key_here odoo-mcp-server

{
  "mcpServers": {
    "odoo-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ODOO_URL=https://example.com/",
        "-e",
        "ODOO_DATABASE=odoo19",
        "-e",
        "ODOO_API_KEY=your_api_key_here",
        "odoo-mcp-server"
      ]
    }
  }
}

Docker 빌드

docker build -t odoo-mcp-server .

Gemini MCP 설정

gemini mcp add --scope user odoo-mcp docker -- run -i --rm --add-host=host.docker.internal:host-gateway -e ODOO_URL=http://host.docker.internal:8069 -e ODOO_DATABASE=odoo19 -e ODOO_API_KEY=your_api_key_here odoo-mcp-server

{
  "mcpServers": {
    "odoo-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--add-host=host.docker.internal:host-gateway",
        "-e",
        "ODOO_URL=http://host.docker.internal:8069",
        "-e",
        "ODOO_DATABASE=odoo19",
        "-e",
        "ODOO_API_KEY=your_api_key_here",
        "odoo-mcp-server"
      ]
    }
  }
}

보안 메커니즘

읽기 전용 모드

READONLY_MODE=true를 설정하여 읽기 전용 모드를 활성화합니다. 운영 환경 조회용으로 적합합니다:

쓰기 도구(create_record, update_record, delete_record, execute_method)는 FastMCP 태그를 통해 직접 숨겨지며, LLM은 이러한 도구를 볼 수 없습니다.

삭제 2차 확인

delete_record는 내장된 확인 메커니즘을 가지고 있습니다. LLM은 먼저 confirm=False로 호출하여 확인 프롬프트를 받아야 하며, 사용자의 동의를 얻은 후 confirm=True로 삭제를 실행해야 합니다.

상태 확인 (Health Check)

HTTP/SSE 전송 모드에서 /health 엔드포인트를 제공합니다:

curl http://localhost:8000/health
# {"status": "healthy", "service": "odoo-mcp-server", "version": "1.0.0"}

Docker healthcheck, Kubernetes probe, 로드 밸런서 상태 확인에 적합합니다. stdio 모드에는 영향을 주지 않습니다.

라이선스

Apache 2.0

odoo19-mcp-server