odoo-surface-mcp

OdooSurface MCP

为 AI Agent 提供与用户等同的 Odoo 访问权限——仅限已认证用户在浏览器中能够执行的操作，不多也不少。

前置条件

• Node.js 18+（自带 npx，无需额外安装）
• 正在运行的 Odoo 实例（15.0+，CE 或 EE）——各版本中每个调用的行为：docs/compatibility.md
• 兼容 MCP 的客户端（VS Code、Claude Desktop、Claude Code、Cursor 等）

配置 MCP 客户端

将以下内容添加到 MCP 客户端配置中（例如 Claude Desktop 的 claude_desktop_config.json）：

{
  "mcpServers": {
    "odoo-surface": {
      "command": "npx",
      "args": ["-y", "@suco/odoo-surface-mcp@latest"],
      "env": {
        "ODOO_URL": "http://localhost:8069",
        "ODOO_DB": "your_database",
        "ODOO_USER": "admin",
        "ODOO_PASSWORD": "admin"
      }
    }
  }
}

保存后重启 MCP 客户端。npx 会自动下载并运行此软件包，无需其他安装步骤。

身份验证

选项 A — .env 文件（避免在 MCP 配置中存放凭据）

无需将凭据写入 MCP 客户端 JSON，可在运行 MCP 的目录中创建 .env 文件：

ODOO_URL=http://localhost:8069
ODOO_DB=your_database
ODOO_USER=admin
ODOO_PASSWORD=your_password

从 MCP 客户端配置中移除 env 区块，系统会自动加载 .env 文件。

选项 B — API Key（推荐，不存储密码）

从 Odoo 14+ 开始，用户可以生成个人 API 密钥，用作密码的替代品。 每位用户都需在自己的账户中生成密钥——管理员端没有对应的菜单。

1. 以 MCP 将要使用的用户身份登录
2. 点击用户头像（右上角）→ Preferences
3. 转到 Account Security 标签页
4. 在 API Keys 下，点击 New API Key
5. 根据提示输入密码，为密钥命名，然后复制生成的密钥
6. 将其用作 ODOO_PASSWORD——实际账户密码不会被存储

ODOO_URL=http://localhost:8069
ODOO_DB=your_database
ODOO_USER=admin
ODOO_PASSWORD=your_api_key_here

无需更改账户密码，即可在同一界面单独撤销 API 密钥。

高级配置

多个 Odoo 实例

技术用户通常需要使用多个 Odoo 实例（本地开发、预发布、生产）。 每个实例在 MCP 配置中都有自己的命名条目——它们作为独立进程运行， 凭据完全隔离。AI 客户端会将它们显示为独立的工具命名空间。

{
  "mcpServers": {
    "odoo-local": {
      "command": "npx",
      "args": ["-y", "@suco/odoo-surface-mcp@latest"],
      "env": {
        "ODOO_URL": "http://localhost:8069",
        "ODOO_DB": "dev",
        "ODOO_USER": "admin",
        "ODOO_PASSWORD": "dev_api_key"
      }
    },
    "odoo-production": {
      "command": "npx",
      "args": ["-y", "@suco/odoo-surface-mcp@latest"],
      "env": {
        "ODOO_URL": "https://mycompany.odoo.com",
        "ODOO_DB": "prod",
        "ODOO_USER": "admin",
        "ODOO_PASSWORD": "prod_api_key"
      }
    }
  }
}

注意： .env 文件方式（选项 A）不适用于多实例配置——两个 进程会共享同一工作目录，并加载相同的文件。请在每个条目中使用 env 区块。

调试模式

注册其他工具：ping、echo、inspect_view、inspect_action、inspect_fields、dump_cache、clear_cache、restart_mcp。

"args": ["-y", "@suco/odoo-surface-mcp@latest", "--debug"]

工具

层级	工具
指引	list_skills、get_skills、find_skill、list_workflows、get_workflows
探索	get_models、get_model_actions、get_model_interface
规划	get_available_actions
支持	list_records、get_record、search_records、read_group、get_fields、get_defaults、get_filters、list_pages、get_page_arch、list_snippets、get_snippet、list_attachments、download_binary、fetch_and_upload、translation_get、translation_update、translation_audit
意图	create、update、execute_action、archive、post_message、schedule_activity、create_page、set_page_arch、set_page_visibility、upload_binary

架构

核心约束

Agent 只能执行经过身份验证的用户在其浏览器中能够执行的操作。范围受限于用户的菜单、视图和 ACL，不得超出。工具动词表达功能意图（发布、确认），而非原始 ORM 操作。发现过程采用惰性方式：Agent 只解析当前提示词所需的内容。

分层工具界面

层级	作用	调用时机
0 — 指引	Agent 在执行任何多步骤操作前查阅的权威方案（技能、工作流）。纯文档，不产生副作用。	规划前
1 — 发现	确定当前用户可访问的模型范围及可达关系。	解析意图时
2 — 规划桥接	回答“此刻这条特定记录上有哪些可执行操作”——感知记录状态的操作。	确定记录后
3 — 辅助	只读数据获取工具，在后台运行，用于补全 Agent 计划中的信息缺口。	贯穿规划过程
4 — 意图	执行用户请求的变更操作——受限于用户在 UI 中的权限。	最终执行

规划循环

User prompt
  ├── Discovery       — what models/relations does this user have?
  ├── (optional)      — locate the specific record
  ├── Planning Bridge — what is live on that record right now?
  ├── Guidance        — consult skills/workflows for multi-step recipes
  └── Intent          — execute the mutation(s)

技能和工作流以带有 YAML frontmatter 的 Markdown 编写，存放在 skills/ 和 workflows/ 中；运行时会将其作为第 0 层工具公开。