Odoo Surface Mcp

io.github.solutionsunityPublished by GitHub account solutionsunityv0.6.1Updated Oct 24, 2026

Full Odoo access for AI agents via MCP: CRUD, website, translations, attachments, workflows.

VerifiedSTDIODesktop onlyProductivity & WorkflowBusiness & Commerce

Overview

AI-generated overview

Local MCP server that gives an AI assistant user-level access to an Odoo instance for records, website pages, translations, attachments and workflows.

What you can do
Discover models, fields, actions and available actions for the authenticated user, and consult built-in skills and workflows before multi-step operations. Read and search records, group data, inspect fields, defaults and filters, and list pages, snippets and attachments. Create, update, archive and execute actions on records, post messages and schedule activities. Manage website pages and snippets, set page architecture and visibility, and upload or download binary files. Read, update and audit translations. Debug mode adds ping, echo, view/action/field inspection and cache tools.
When to use it
Useful when an assistant should work inside an existing Odoo ERP or website — looking up and editing business records, maintaining web pages, handling translations or attachments — with the same permissions the logged-in user has in the browser.
Requirements
Runs locally via npx, so Node.js 18+ is needed. Requires a reachable Odoo instance (15.0+, CE or EE) and an MCP-compatible client. Set ODOO_URL, ODOO_DB, ODOO_USERNAME and ODOO_PASSWORD (an Odoo API key is recommended) either in the client env block or a .env file; multi-instance setups need per-entry env blocks.
Before you install
The server holds Odoo credentials in ODOO_PASSWORD; prefer a personal API key over the account password and keep it out of shared configs. It can create, update, archive, publish and upload data in Odoo, bounded only by the user's permissions, so a misdirected request can change live records or website content. Point it at a test instance first when possible.

Installation

In SourceWeft

  1. Open Odoo Surface Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[Image] OdooSurface MCP

[npm version] [Node] [Odoo] [License: Apache 2.0] [Downloads]

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):

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:

ini
ODOO_URL=http://localhost:8069ODOO_DB=your_databaseODOO_USER=adminODOO_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
ini
ODOO_URL=http://localhost:8069ODOO_DB=your_databaseODOO_USER=adminODOO_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.

json
{  "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.

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

Tools

LayerTools
Guidancelist_skills, get_skills, find_skill, list_workflows, get_workflows
Discoveryget_models, get_model_actions, get_model_interface
Planningget_available_actions
Supportinglist_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
Intentcreate, 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

LayerRoleWhen invoked
0 — GuidanceCanonical recipes (skills, workflows) the agent consults before any multi-step operation. Pure documentation, no side effects.Before planning
1 — DiscoveryEstablishes the bounded universe of models and reachable relations for the current user.At intent resolution
2 — Planning BridgeAnswers "what is live on this specific record right now" — record-state-aware actions.Once a record is identified
3 — SupportingRead-only data fetchers used silently to fill gaps in the agent's plan.Throughout planning
4 — IntentMutating 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.

Source: README.md at commit 51902ef

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v0.6.1LatestOct 3, 2026
  2. v0.4.6Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts