suco-odoo-surface-mcp 0.1.0

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 (14–17, CE or EE) and an MCP-compatible client (e.g. Claude Desktop).

Install uv

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

macOS

brew install uv

Windows

winget install --id=astral-sh.uv

Linux

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

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"],
      "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", "--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.