cf-odoo-mcp-server

MCP 서버 — Cloudflare Workers에서 실행되는 Odoo ERP용

stateless HTTP transport 사용 — Durable Objects 불필요, container 불필요, 상주 프로세스 불필요, Workers free tier에 충분히 들어갑니다.

odoo-mcp-claude에서 포팅했으며 동일한 10개 tool 세트를 제공하지만 Python 프로세스로 실행되어 XML-RPC로 통신합니다.

Odoo 19에는 API key 2종류가 있습니다 — 어떤 것을 써야 하는지 먼저 확인하세요

Odoo 19는 2가지 scope의 API key를 발급할 수 있으며 서로 대체할 수 없습니다.

scope 구분은 양방향으로 엄격합니다: rpc 종류 key로 /mcp를 호출하면 401이 뜨고, mcp 종류 key는 JSON-RPC로 인증할 수 없습니다.

그래서 이 프로젝트를 아예 안 써도 될 수도 있습니다. agent가 읽기 전용이라면 Odoo 내장 MCP server는 deploy도, hosting도, Odoo 코드를 다른 곳에 올릴 필요도 없습니다 — client를 https://<당신의-odoo>/mcp로 지정하고 mcp 종류 key를 쓰면 끝입니다. 게다가 technical model도 거부해 주는데, 이 프로젝트에는 없는 guardrail입니다.

쓰기 작업이 필요한 경우 rpc 종류 key가 필요하며, 이것이 이 프로젝트가 존재하는 이유입니다 — 단일 endpoint로 여러 Odoo 인스턴스에 연결하는 경우와 읽기 시 기본 상한선을 두는 경우도 포함됩니다. 둘 다 병행 실행할 수 있습니다.

NOTES.md에 전체 비교 결과가 있으며, 내장 MCP server의 schema가 agent를 헷갈리게 만드는 지점도 포함되어 있습니다.

왜 XML-RPC가 아니라 JSON-RPC인가

Python의 xmlrpc.client는 raw socket이 필요한데 Workers runtime에는 없습니다. 하지만 Odoo는 /jsonrpc에서 동일한 execute_kw 세트를 JSON-RPC로 제공하며 이는 일반 HTTP라서 fetch로 바로 사용할 수 있고 수정할 것도 없습니다.

요구 사항

Odoo는 HTTPS를 통해 인터넷에서 접근 가능해야 합니다 — Worker는 LAN으로는 실행할 수 없습니다. Odoo가 아직 public이 아니라면 Cloudflare Tunnel을 앞에 끼워 넣으세요.

Tools

설정

계정 비밀번호 대신 Odoo API key를 사용하고, 해당 계정에 tool이 실제로 필요한 권한만 부여하세요 — odoo_delete와 odoo_write는 해당 계정이 접근할 수 있는 모든 것에 접근할 수 있습니다.

ODOO_SERVERS 형식은 다음과 같습니다.

{
  "default_server": "prod",
  "servers": {
    "prod": { "url": "https://odoo.example.com", "db": "mydb", "username": "bot@example.com", "password": "api-key" }
  }
}

로컬에서 개발

npm install
cp .dev.vars.example .dev.vars   # แล้วกรอกค่าให้ครบ
npm run dev

.dev.vars는 gitignore 처리되어 있으니 절대 비밀번호를 commit하지 마세요.

Deploy

npx wrangler login
npx wrangler deploy

npx wrangler secret put MCP_AUTH_TOKEN     # openssl rand -hex 32
npx wrangler secret put ODOO_URL
npx wrangler secret put ODOO_DB
npx wrangler secret put ODOO_USERNAME
npx wrangler secret put ODOO_PASSWORD

secret은 저장 시 암호화되며 wrangler.jsonc에 노출되지 않습니다.

client 연결

이 폴더의 .mcp.json은 Claude Code용 파일이지 Worker용이 아닙니다 — 단지 client에게 어떤 endpoint에 어떤 token으로 통신할지 알려줄 뿐입니다. 이 파일은 environment 값을 참조하므로 비밀이 포함되어 있지 않아 git에 commit할 수 있습니다.

{
  "mcpServers": {
    "odoo": {
      "type": "streamable-http",
      "url": "${ODOO_MCP_URL:-https://cf-odoo-mcp-server.<subdomain>.workers.dev/mcp}",
      "headers": { "Authorization": "Bearer ${MCP_AUTH_TOKEN}" }
    }
  }
}

Claude Code는 .env를 자동으로 로드하지 않으므로 호출 전에 environment로 export해야 합니다.

cp .env.example .env    # แล้วกรอก MCP_AUTH_TOKEN
set -a; . ./.env; set +a
claude

export를 잊으면 변수가 치환되지 않고 claude mcp list가 변수를 찾을 수 없다고 경고하며 Worker는 401로 응답합니다 — 조용히 실패하는 것이 아니라 인지할 수 있게 실패합니다.

ODOO_MCP_URL은 staging과 production처럼 다른 Worker를 가리킬 때 사용하며 .mcp.json을 수정할 필요가 없습니다.

.mcp.json을 읽지 않는 다른 client는 동일한 형식으로 endpoint와 Authorization: Bearer <token> 헤더를 직접 설정하세요.

GET /health는 인증이 필요 없으며 {"status":"ok"}를 반환합니다.

보안

이 endpoint는 public이므로 /mcp로 들어오는 모든 request에는 bearer token이 첨부되어야 하며 constant time으로 비교됩니다. MCP_AUTH_TOKEN이 설정되지 않으면 Worker는 열어두는 대신 500을 반환합니다.

단일 공유 token은 개인 서버나 내부용에 적합합니다. 사용자별 식별이 필요하면 Workers OAuth Provider를 앞에 끼워 넣는 방식으로 대체하세요.

실제 사용 기록

NOTES.md에는 실제 Odoo로 테스트한 내용과 AI agent가 이러한 tool을 조작할 때의 중요한 주의 사항이 기록되어 있습니다 — 특히 Odoo가 readonly field에 작성된 값을 조용히 버리는 문제에 대해 다룹니다.

License

MIT