cf-odoo-mcp-server

MCP 服务器，用于运行在 Cloudflare Workers 上的 Odoo ERP。

使用无状态 HTTP 传输——不需要 Durable Objects，不需要容器，也没有常驻进程，可以安稳地待在 Workers 的免费额度里。

移植自 odoo-mcp-claude，它提供同样的一套 10 个工具，但以 Python 进程运行，通过 XML-RPC 通信。

Odoo 19 有 2 种 API key——先确认要用哪一种

Odoo 19 可以签发 2 种 scope 的 API key，二者不能互换。

Scope 的划分是双向严格的：rpc 类型的 key 请求 /mcp 会得到 401；mcp 类型的 key 也无法通过 JSON-RPC 认证。

所以如果你的 agent 是只读的，你可能完全不需要这个项目。 Odoo 内置的 MCP server 不需要部署，不需要找托管，也不需要把 Odoo 密码放到别处——直接把 client 指向 https://<odoo-ของคุณ>/mcp 并配上 mcp 类型的 key 就行；而且它还会拒绝 technical model，这是本项目没有的 guardrail。

需要写入数据的任务必须使用 rpc 类型的 key，这正是本项目的存在理由——包括通过一个 endpoint 连接多台 Odoo，以及提供默认的读取上限。两者可以并行运行。

NOTES.md 有完整对比，包括内置 MCP server 的 schema 会让 agent 卡住的地方。

为什么用 JSON-RPC 而不用 XML-RPC

Python 的 xmlrpc.client 需要 raw socket，而 Workers runtime 没有；不过 Odoo 在 /jsonrpc 上通过 JSON-RPC 暴露了同一套 execute_kw，这是普通 HTTP，可以直接用 fetch 调用，不需要任何改造。

要求

Odoo 必须能从互联网通过 HTTPS 访问——Worker 无法进入 LAN。如果 Odoo 还未公网，请在前面加一层 Cloudflare Tunnel。

工具

配置

建议使用 Odoo API key 而不是账户密码，并且只给该账户工具实际需要的权限——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，绝对不要提交密码。

部署

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 中。

接入客户端

此文件夹中的 .mcp.json 是 Claude Code 这里的文件，不是 Worker 的——它只是告诉客户端用 token、访问哪个 endpoint。这个文件引用的是环境变量，因此本身不含机密信息，可以提交到 git。

{
  "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，必须在调用前 export 到环境中。

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

如果忘记 export，变量就不会被替换；claude mcp list 会提示找不到某个变量，Worker 也会返回 401——它是可见的故障，不会无声漏过。

ODOO_MCP_URL 用来指向另一个 Worker，例如在 staging 和 production 之间切换，而不必修改 .mcp.json。

其他不读取 .mcp.json 的客户端，请自己按同样格式设置 endpoint 和 Authorization: Bearer <token> 请求头。

GET /health 无需认证，返回 {"status":"ok"}。

安全性

这个 endpoint 是公开的，因此每个到达 /mcp 的请求都必须携带 Bearer token，并以常量时间进行比较。如果未设置 MCP_AUTH_TOKEN，Worker 会返回 500，而不是向所有开放。

单个 token 共享使用适合个人 server 或内部使用；如果需要按用户逐人区分身份，请在前面加一层 Workers OAuth Provider。

实际使用记录

NOTES.md 记录了与真实 Odoo 实测后的结果，以及让 AI agent 驱动这些工具时的重要注意事项——尤其是 Odoo 会悄悄丢弃写入 readonly 字段的值这件事。

许可证

MIT