suco-odoo-surface-mcp 0.1.2

User-equivalent Odoo access for AI agents via MCP

OdooSurface MCP

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

Prerequisites

A running Odoo instance (16.0+, CE or EE) and an MCP-compatible client (e.g. VS Code, Claude Desktop, Claude Code).

Install uv

uv is the Python runner used to launch the server — no manual Python or pip setup needed.

macOS

brew install uv

Then make uvx visible to MCP clients (non-login shells):

sudo ln -s $(which uvx) /usr/local/bin/uvx

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Then make uvx visible to MCP clients (non-login shells):

sudo ln -s $(which uvx) /usr/local/bin/uvx

Important: After installing uv, fully close and reopen your AI client (VS Code, Claude Code, Claude Desktop, etc.) so it picks up the new uvx command.

Configure your MCP client

Add this to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "odoo-surface": {
      "command": "uvx",
      "args": ["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. uvx downloads and runs the package automatically — no further install steps.

Debug mode

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

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

Tools

Layer	Tools
Discovery	get_models, get_model_actions
Planning	get_available_actions
Supporting	list_records, get_record, search_records, get_fields, get_defaults, get_filters, list_snippets, get_snippet
Intent	create, update, execute_action, archive, post_message, schedule_activity

Architecture

See SURFACE.md for the design contract, layer rationale, and planning loop.