Odoo Assistant MCP 서버

Model Context Protocol(MCP)을 통한 Odoo 가상 직원입니다. 이 서버는 Odoo의 비즈니스 로직, 레코드, 워크플로우를 LLM에 노출하여 안전하게 Odoo 데이터를 조회, 생성, 업데이트 및 작업할 수 있도록 합니다.

빠른 시작

1. 설치

서버를 직접 실행:

uvx odoo-assistant

또는 환경에 설치:

uv pip install odoo-assistant

개발을 위해 소스에서 설치하는 것도 가능합니다:

uv pip install git+https://github.com/singleflo/odoo-assistant-mcp

2. 환경 변수 구성

두 개의 변수가 필수이며, 나머지는 자동으로 발견되거나 기본값이 있습니다:

• ODOO_BASE_URL: Odoo 인스턴스의 기본 URL (예: https://mycompany.odoo.com).

• ODOO_API_KEY: Odoo API 키 (Odoo 14+, 설정 > 사용자 > API 키 > 새로 만들기에서 생성). 계정 비밀번호는 허용되지 않습니다: 키는 사용자별로, 범위가 지정되고 자체적으로 취소 가능합니다.

선택적 구성:

• ODOO_DB: 데이터베이스 이름. 인스턴스가 정확히 하나의 데이터베이스를 제공할 때 자동으로 발견됨; 여러 개를 제공할 때 필요하며, 오류 메시지에 모든 이름이 표시됩니다.

• ODOO_USER: 로그인. 키에서 발견되지만 최대 59회의 추가 왕복이 필요할 수 있음; 키 소유자의 uid가 60 이상이면 발견 실패. 설정하면 프로브를 절약합니다.

• ODOO_MCP_MAX_LEVEL: 이 서버가 실행할 수 있는 최고 안전 수준, 0에서 4까지 (기본값: 3). 서버를 읽기 전용으로 만들거나 삭제를 허용하는 방법입니다 — 상한 선택 참조.

• ODOO_MCP_PROTECTED_HOSTS: 이 서버가 쓰기를 거부하는 호스트 목록 (쉼표로 구분, 기본값은 비어 있음 — 패키지에 내장된 호스트 없음). 나열된 호스트는 여전히 읽기를 허용하며, 쓰기를 위해서는 의도적인 재정의로 ODOO_ALLOW_PROD_WRITE=yes가 필요합니다.

Related MCP server: mcp-server-odoo

안전 계층

모든 쓰기 및 작업은 Odoo에 도달하기 전에 동적 안전 분류기를 통과합니다. 작업은 L0에서 L5까지의 수준으로 분류됩니다:

상한 선택

ODOO_MCP_MAX_LEVEL은 이 서버가 실행할 수 있는 최고 수준을 설정합니다. 각 값은 누적됩니다 — 자신의 수준과 그 아래 모든 것을 허용합니다:

숫자를 선택하기 전에 알아야 할 두 가지 동작이 있습니다:

• 5는 L5를 잠금 해제하지 않습니다. 두 L5 변형 모두 상한이 읽히기 전에 거부됩니다. L5_PRIVATE는 Odoo 자체가 _로 시작하는 모든 메서드를 거부하므로 어떤 상한도 제공할 수 없기 때문에 거부됩니다; L5_UNKNOWN은 분류되지 않은 메서드는 정의상 검토되지 않은 효과를 가지므로 거부됩니다. 이러한 메서드를 허용하는 방법은 safety_layer.py의 WRITE_L1/L3/L4에 추가하는 것입니다 — 코드에서 검토됨 — 결코 구성을 통해서가 아닙니다.

• 잘못된 값은 시작을 거부합니다. ODOO_MCP_MAX_LEVEL="O"는 기본값으로 대체되지 않고 오류를 발생시킵니다. 기본값이 쓰기 가능하기 때문입니다: 오타로 인해 읽기 전용이라고 믿었던 서버가 쓰기 가능한 서버가 되어서는 안 됩니다.

상한은 사람이 대역 외에서 설정하며, 시작 시 프로세스 환경에서 읽힙니다. 이 서버에 대해 실행되는 모델은 이를 높일 수 없습니다; 호출이 상한을 초과하면 거부 메시지에 필요한 수준이 명시되므로, 에이전트는 작업이 무엇을 변경할지 설명하고 결정을 사용자에게 맡길 수 있습니다.

이는 이 서버의 권한이지 계정의 권한이 아닙니다. 셸 액세스 권한이 있는 에이전트는 Odoo를 직접 호출하여 MCP 서버를 우회할 수 있습니다. 클라이언트에 관계없이 유지되어야 하는 제한은 API 키가 속한 사용자의 Odoo 액세스 권한에 속하며, Odoo 서버가 이를 강제합니다.

Odoo 버전 지원

Odoo 14.0은 지원되는 최소 버전입니다. 이 서버는 API 키로만 인증하며, Odoo 13 이하에는 존재하지 않습니다.

API 키 생성 경로

API 키를 생성하려면 Odoo 인스턴스에 로그인하고 다음으로 이동하세요: 환경 설정 / 내 프로필 → 계정 보안 → 새 API 키

전송 및 지원 중단 참고 사항

클라이언트는 기본 JSON-2 API가 /json/2/<model>/<method>에서 사용 가능한지 자동으로 감지하고(이 API는 Authorization: bearer <API_KEY>를 사용), 사용 불가능한 경우 XML-RPC로 대체합니다. XML-RPC 및 JSON-RPC는 Odoo 19에서 지원 중단되었으며 Odoo 22에서 제거될 예정입니다.

출처

• Odoo 14.0 외부 API 문서 (API 키 소개)

• Odoo 19.0 외부 API 문서 (JSON-2)

• Odoo 19.0 외부 RPC API 문서 (XML-RPC 지원 중단)

• Odoo 표준 및 확장 지원 정책 (지원 일정)

도구 및 리소스

서버는 19개의 도구와 2개의 리소스 유형을 제공합니다:

도구

1. search_read: 한 번의 호출로 레코드 검색 및 읽기 (Odoo search_read).

2. read_record: ID로 하나의 레코드를 읽으며, 항상 명명된 필드를 사용합니다.

3. count_records: 도메인과 일치하는 레코드 수 계산 (Odoo search_count).

4. instance_overview: 연결된 인스턴스 요약: 버전, 회사, 영역별 볼륨, 사내 모듈, 이상 징후.

5. required_fields: Odoo가 모델에 대해 create 전에 요구하는 사항, 적용할 기본값, 기존 레코드가 실제로 이를 사용하는 방법을 나열합니다.

6. create_record: 레코드를 생성하며, unique_on이 주어지면 기존 일치 항목을 재사용합니다.

7. write_record: 하나의 레코드에 필드 값을 쓰고 실제로 변경된 사항을 보고합니다.

8. run_action: 워크플로우 메서드를 실행하고 남은 상태를 보고합니다.

9. cancel_record: action_cancel을 통해 레코드를 취소하고, 반환된 마법사를 따릅니다.

10. notify_user: 레코드의 채터에서 사용자에게 알림. 기본적으로 내부 알림입니다.

11. create_activity: 활동 예약: 마감일이 있는 유일한 알림 유형입니다.

12. download_docs: 레코드의 모든 문서를 디스크에 저장하며, 채터 파일도 포함됩니다.

13. generate_pdf: 레코드의 PDF를 렌더링하고 저장된 위치를 반환합니다.

14. list_message_targets: 메시지를 보낼 수 있는 사람과 위치를 나열 — 온라인/자리비움/오프라인 상태의 내부 사용자와 호출자의 열린 대화. 보내기 전에 먼저 물어보세요.

15. read_conversation: Discuss 대화를 읽으며, 최신 항목이 먼저 옵니다.

16. send_direct_message: 사용자의 채팅 시스템 트레이에 실시간으로 표시되는 1:1 Discuss 메시지를 보냅니다 — 이메일 없음, 알림 설정에 관계없이 도달합니다.

17. send_channel_message: 기존 Discuss 채널에 게시하며, 비직원이 있는 방은 거부합니다.

18. explore_module: 라이브 인스턴스를 조회하여 모듈의 구조를 발견합니다.

19. list_known_modules: 이 서버가 학습한 모듈 목록: 이름, 생성 날짜, 레코드.

도구 10-11(notify_user, create_activity)은 레코드에 대해 알리고 받은 편지함 벨에 도착합니다; 도구 14-17은 채팅 시스템 트레이에 도착하는 Discuss 대화입니다. "사용자 X에게 메시지 보내기"는 두 번째 종류입니다 — notify_user가 아닌 send_direct_message입니다.

리소스

• odoo://skill: Odoo 어시스턴트 스킬 지침에 액세스합니다.

• odoo://ref/*: 탐색된 모듈에 대한 생성된 참조 문서에 액세스합니다.

호스트 구성 예제

아래의 모든 예제는 필수 사항만 포함합니다: 두 개의 필수 변수와 상한 — 서버가 쓸 수 있는지 여부를 결정하는 단일 설정으로, 사람이 소유한 파일에 표시됩니다. 데이터베이스와 로그인은 자동으로 발견되며, 3은 상한의 기본값입니다. 따옴표에 주의하세요: 환경 값은 문자열입니다.

Claude Desktop

claude_desktop_config.json에 다음을 추가하세요:

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

Cursor

.cursor/mcp.json에 추가하거나 Cursor 설정 UI에서 구성하세요:

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

VS Code Copilot

VS Code settings.json에 다음을 추가하세요:

{
  "mcp.servers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

opencode

프로젝트의 opencode.json 또는 .opencode/opencode.json에 추가하거나, ~/.config/opencode/opencode.json에 추가하여 서버를 모든 곳에서 사용할 수 있게 하세요:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "odoo-assistant": {
      "type": "local",
      "enabled": true,
      "command": [
        "uvx",
        "odoo-assistant"
      ],
      "timeout": 120000,
      "environment": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

opencode의 형식은 위 호스트들과 여러 면에서 다릅니다: 키는 mcp (mcpServers 아님), type은 필수, command는 프로그램 과 그 인수를 포함하는 단일 배열 (args는 별도로 없음), 환경 블록은 environment (env 아님)입니다.

timeout을 의도적으로 설정하세요. 기본값은 5000ms이며, 세션의 첫 번째 호출은 인증 비용을 지불하고, instance_overview의 경우 수십 번의 XML-RPC 왕복이 발생합니다 — 실제 인스턴스에 대해 5초를 훨씬 넘깁니다.

opencode는 시작 시 한 번만 구성을 읽고 핫 리로드하지 않으므로, 편집 후 종료하고 다시 시작하세요. 여기서 변경하는 모든 사항(상한 포함)은 다음 실행 시에만 적용됩니다.

ChatGPT (Custom Connectors)

Custom Connectors를 통해 이 서버를 ChatGPT에 연결하려면:

1. 설정 → 커넥터 → 커넥터 추가로 이동합니다.

2. 서버 URL을 입력하거나 레지스트리에서 선택합니다.

3. 메시지가 표시되면 Odoo 자격 증명을 입력합니다.

Hermes

Hermes CLI를 사용하여 서버를 추가합니다:

hermes mcp add odoo-assistant \
  --env ODOO_BASE_URL=https://mycompany.odoo.com \
  --env ODOO_API_KEY=your-api-key-here \
  --env ODOO_MCP_MAX_LEVEL=3 \
  --args run odoo-assistant

예제에서는 선택적 변수를 생략했습니다. 인스턴스가 여러 데이터베이스를 제공하는 경우 ODOO_DB를 설정하고, uid 프로브를 건너뛰려면 ODOO_USER를 설정하며, 기본값 3에서 상한을 변경하려면 ODOO_MCP_MAX_LEVEL을 설정합니다.

License

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.