odoo-surface-mcp

OdooSurface MCP

User-equivalent Odoo access for AI agents — what the authenticated user can do in their browser, nothing more.

Prerequisites

• Node.js 18+ (ships with npx — no extra install needed)
• A running Odoo instance (15.0+, CE or EE) — per-version behaviour of every call: docs/compatibility.md
• An MCP-compatible client (VS Code, Claude Desktop, Claude Code, Cursor, …)

Configure your MCP client

Add this to your MCP client config (e.g. 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"
      }
    }
  }
}

Restart your MCP client after saving. npx downloads and runs the package automatically — no further install steps.

Authentication

Option A — .env file (keep credentials out of MCP config)

Instead of putting credentials in your MCP client JSON, create a .env file in the directory where you run the MCP:

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

Remove the env block from the MCP client config — the .env file is loaded automatically.

Option B — API Key (recommended, no password stored)

Since Odoo 14+, users can generate personal API keys that act as a password replacement. Each user generates their own key from their own account — there is no admin-side menu for this.

1. Log in as the user the MCP will authenticate as
2. Click the user avatar (top-right) → Preferences
3. Go to the Account Security tab
4. Under API Keys → click New API Key
5. Enter your password when prompted, give the key a name, copy the generated key
6. Use it as ODOO_PASSWORD — the actual account password is never stored

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

API keys can be revoked individually from the same screen without changing the account password.

Advanced Configuration

Multiple Odoo instances

Technical users commonly work with more than one Odoo instance (local dev, staging, production). Each instance gets its own named entry in the MCP config — they run as independent processes with fully isolated credentials. The AI client exposes them as separate tool namespaces.

{
  "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"
      }
    }
  }
}

Note: The .env file approach (Option A) does not work for multi-instance setups — both processes share the same working directory and would load the same file. Use the env block per entry instead.

Debug mode

Registers additional tools: ping, echo, inspect_view, inspect_action, inspect_fields, dump_cache, clear_cache, restart_mcp.

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

Tools

Layer	Tools
Guidance	list_skills, get_skills, find_skill, list_workflows, get_workflows
Discovery	get_models, get_model_actions, get_model_interface
Planning	get_available_actions
Supporting	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
Intent	create, update, execute_action, archive, post_message, schedule_activity, create_page, set_page_arch, set_page_visibility, upload_binary

Architecture

Core Contract

The agent may only do what the authenticated user can do in their browser. Scope is bounded by the user's menus, views, and ACL — nothing more. Tool verbs express functional intent (publish, confirm) rather than raw ORM operations. Discovery is lazy: the agent resolves only what the current prompt requires.

Layered Tool Surface

Layer	Role	When invoked
0 — Guidance	Canonical recipes (skills, workflows) the agent consults before any multi-step operation. Pure documentation, no side effects.	Before planning
1 — Discovery	Establishes the bounded universe of models and reachable relations for the current user.	At intent resolution
2 — Planning Bridge	Answers "what is live on this specific record right now" — record-state-aware actions.	Once a record is identified
3 — Supporting	Read-only data fetchers used silently to fill gaps in the agent's plan.	Throughout planning
4 — Intent	Mutating actions that fulfill the user's request — bounded by the user's UI permissions.	Final execution

Planning Loop

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)

Skills and workflows are authored in skills/ and workflows/ as markdown with YAML frontmatter; they are exposed as Layer 0 tools at runtime.