Odoo MCP

Odoo MCP는 Odoo 데이터베이스를 Model Context Protocol 서버로 변환합니다. 이 서버는 직접 작성한 스크립트나 안전하지 않은 직접 쓰기 권한 없이 실제 Odoo 컨텍스트가 필요한 로컬 에이전트, IDE 및 자동화 도구를 위해 구축되었습니다.

Odoo 16-18용 XML-RPC와 Odoo 19용 External JSON-2를 지원합니다. 읽기 도구, 진단, 스키마 검색, 마이그레이션 도우미, 로컬 애드온 스캔 및 게이트가 적용된 쓰기 워크플로우를 포함하는 간결한 MCP 인터페이스를 제공합니다.

주요 기능

Related MCP server: Odoo MCP Server

설치

pip install odoo-mcp

로컬 개발 환경:

git clone https://github.com/tuanle96/mcp-odoo.git
cd mcp-odoo
uv sync --extra dev

구성

환경 변수에 연결 값을 설정합니다:

export ODOO_URL="https://your-odoo-instance.com"
export ODOO_DB="your-database"
export ODOO_USERNAME="your-user"
export ODOO_PASSWORD="your-password-or-api-key"
export ODOO_TRANSPORT="xmlrpc"

Odoo 19 JSON-2의 경우:

export ODOO_TRANSPORT="json2"
export ODOO_API_KEY="your-odoo-api-key"
export ODOO_JSON2_DATABASE_HEADER="1"

ODOO_JSON2_DATABASE_HEADER=1은 JSON-2 호출 시 X-Odoo-Database 헤더를 전송합니다. 호스트나 dbfilter 라우팅이 이미 의도한 데이터베이스를 선택하는 경우에만 0으로 설정하십시오.

odoo_config.json을 사용할 수도 있습니다:

{
  "url": "https://your-odoo-instance.com",
  "db": "your-database",
  "username": "your-user",
  "password": "your-password-or-api-key"
}

실행

stdio를 통해 MCP 서버 시작:

odoo-mcp

또는:

python -m odoo_mcp

로컬 클라이언트를 위한 스트리밍 HTTP 시작:

odoo-mcp --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp

--allow-remote-http를 전달하거나 MCP_ALLOW_REMOTE_HTTP=1을 설정하지 않으면 로컬이 아닌 HTTP 바인딩은 거부됩니다. 이 서버에는 내장 HTTP 인증이 포함되어 있지 않습니다. 원격 HTTP 배포 시 자체 인증, TLS 및 네트워크 정책을 적용하십시오.

서버 루프를 시작하지 않고 런타임 상태 확인:

odoo-mcp --health

MCP 도구

리소스

프롬프트

안전한 쓰기 모델

쓰기는 의도적으로 엄격하게 제한됩니다.

1. preview_write는 표준화된 비실행 페이로드를 생성합니다.

2. validate_write는 모델 메타데이터, 필수 필드, 읽기 전용 필드, 관계 힌트, 레코드 ID 및 페이로드 형태를 확인합니다.

3. execute_approved_write는 모든 게이트를 통과할 때만 실행됩니다:

   • 승인이 동일한 서버 프로세스 내의 validate_write에서 발생함,

   • 검증 시 신뢰할 수 있는 비어 있지 않은 실시간 Odoo fields_get 메타데이터를 사용함,

   • 토큰이 만료되거나 소비되지 않음,

   • confirm=true가 전달됨,

   • ODOO_MCP_ENABLE_WRITES=1이 설정됨.

Odoo 액세스 규칙, 레코드 규칙 및 서버 측 제약 조건이 최종 결과를 결정합니다.

sale.order.action_confirm과 같이 검토된 부작용 메서드는 하나씩 활성화할 수 있습니다:

export ODOO_MCP_ALLOWED_SIDE_EFFECT_METHODS="sale.order.action_confirm,res.partner.message_post"

ODOO_MCP_ALLOW_UNKNOWN_METHODS=1은 신뢰할 수 있는 배포를 위해 여전히 지원되지만, health_check는 이를 광범위한 모드로 보고합니다. 소수의 검토된 메서드만 필요한 경우 정확한 허용 목록 항목을 사용하는 것이 좋습니다.

클라이언트 설정

macOS의 Claude Desktop은 다음 위치에서 MCP 구성을 읽습니다:

~/Library/Application Support/Claude/claude_desktop_config.json

GUI 앱은 셸의 PATH를 상속받지 않을 수 있으므로 절대 Python 경로를 사용하십시오:

{
  "mcpServers": {
    "odoo": {
      "command": "/opt/homebrew/bin/python3",
      "args": ["-m", "odoo_mcp"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_DB": "your-database",
        "ODOO_USERNAME": "your-user",
        "ODOO_PASSWORD": "your-password-or-api-key",
        "ODOO_TRANSPORT": "xmlrpc"
      }
    }
  }
}

더 많은 예제는 docs/client-configs.md를 참조하십시오.

Docker

이미지 빌드:

docker build -t mcp/odoo:latest -f Dockerfile .

MCP 클라이언트에서 stdio를 통해 실행:

{
  "mcpServers": {
    "odoo": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "ODOO_URL",
        "-e", "ODOO_DB",
        "-e", "ODOO_USERNAME",
        "-e", "ODOO_PASSWORD",
        "-e", "ODOO_TRANSPORT",
        "-e", "ODOO_API_KEY",
        "mcp/odoo:latest"
      ]
    }
  }
}

로컬에서 스트리밍 HTTP 실행:

docker run --rm \
  -p 127.0.0.1:8000:8000 \
  -e ODOO_URL \
  -e ODOO_DB \
  -e ODOO_USERNAME \
  -e ODOO_PASSWORD \
  -e ODOO_TRANSPORT \
  -e ODOO_API_KEY \
  mcp/odoo:latest \
  --transport streamable-http \
  --host 0.0.0.0 \
  --port 8000 \
  --allow-remote-http

테스트

일반 품질 게이트 실행:

uv run python -m ruff check .
uv run python -m mypy src
uv run python -m pytest

실제 Odoo 스모크 테스트 실행:

uv run --python 3.12 --with-editable . scripts/odoo_compose_smoke.py \
  --versions 16.0 17.0 18.0 19.0 \
  --timeout 360 \
  --inspector-smoke

스모크 하네스는 일회용 Docker Compose 스택을 부팅하고, 직접적인 Odoo 액세스를 검증하며, MCP stdio를 검증하고, Odoo 19의 경우 JSON-2 및 스트리밍 HTTP도 검증합니다.

호환성

XML-RPC는 광범위한 호환성을 위해 기본 전송 방식으로 유지됩니다. Odoo 19는 ODOO_TRANSPORT=json2를 통해 External JSON-2를 지원합니다. Odoo는 Odoo 20에서 XML-RPC 및 JSON-RPC 지원 중단을 예고했으므로, 새로운 통합은 JSON-2를 계획해야 합니다.

기여

이슈, 풀 리퀘스트 및 호환성 보고서를 환영합니다. CONTRIBUTING.md에서 시작하고, Odoo 버전, 전송 방식, 클라이언트 유형 및 실행한 검증 내용을 포함하십시오.

보안

Odoo 자격 증명, API 키, 개인 환경의 데이터베이스 이름 또는 전체 Odoo 디버그 추적이 포함된 로그를 게시하지 마십시오. 취약점은 SECURITY.md를 통해 보고하십시오.

라이선스

MIT. LICENSE를 참조하십시오.