Odoo Surface MCP server

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 (17.0+, CE or EE)
• 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 claudedesktopconfig.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, inspectview, inspectaction, inspectfields, dumpcache, clearcache, restartmcp.

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

Tools

Shortened. The full README is on GitHub.