Enables AI agents to perform CRUD operations, manage websites, translations, and workflows within an Odoo instance.
Also known as solutionsunity/odoo-surface-mcp, @suco/odoo-surface-mcp
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.6.1
- Last commit
- Oct 3, 2026
- License
- Apache-2.0
What is OdooSurface MCP?
OdooSurface enables AI agents to perform CRUD operations, manage websites, translations, and workflows within an Odoo instance.
Summary generated from the project's README
About OdooSurface MCP server
OdooSurface MCP provides AI agents with access to Odoo instances, allowing them to perform tasks exactly as an authenticated user would in a web browser. This server works with Odoo versions 15.0 and higher, including both Community and Enterprise editions. It is designed for use with MCP-compatible clients such as Claude Desktop, Cursor, VS Code, or Claude Code. Users can connect to local or remote instances by configuring the ODOO_URL, ODOO_DB, ODOO_USER, and ODOO_PASSWORD in their client settings.
The toolset is organized into functional layers ranging from guidance and discovery to intent execution. Agents can use tools like list_records and search_records to find data, or execute mutations through tools like create, update, and execute_action. For developers managing multiple environments, the server supports running independent processes for local, staging, and production instances. Security is maintained by restricting all actions to the permissions and access control lists of the authenticated user, and using personal API keys is the recommended method for authentication.
What you can do with it
- 1Manage Odoo recordsAn AI agent can search for specific entries and perform CRUD operations on them.
- 2Execute complex workflowsThe agent can follow predefined recipes to complete multi-step business processes.
Written from the project's README. Every use case is checked against a quote from it.
How to install OdooSurface MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall OdooSurface MCP in Claude Code
$ claude mcp add --env 'ODOO_PASSWORD=<YOUR_ODOO_PASSWORD>' --env 'ODOO_DB=<ODOO_DB>' --env 'ODOO_URL=<ODOO_URL>' --env 'ODOO_USERNAME=<ODOO_USERNAME>' odoo-surface-mcp -- npx -y @suco/odoo-surface-mcpInstall OdooSurface MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"odoo-surface-mcp": {
"command": "npx",
"args": [
"-y",
"@suco/odoo-surface-mcp"
],
"env": {
"ODOO_PASSWORD": "<YOUR_ODOO_PASSWORD>",
"ODOO_DB": "<ODOO_DB>",
"ODOO_URL": "<ODOO_URL>",
"ODOO_USERNAME": "<ODOO_USERNAME>"
}
}
}
}Install OdooSurface MCP in VS Code
.vscode/mcp.json
{
"servers": {
"odoo-surface-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@suco/odoo-surface-mcp"
],
"env": {
"ODOO_PASSWORD": "<YOUR_ODOO_PASSWORD>",
"ODOO_DB": "<ODOO_DB>",
"ODOO_URL": "<ODOO_URL>",
"ODOO_USERNAME": "<ODOO_USERNAME>"
}
}
}
}Install OdooSurface MCP in VS Code CLI
$ code --add-mcp '{"name":"odoo-surface-mcp","type":"stdio","command":"npx","args":["-y","@suco/odoo-surface-mcp"],"env":{"ODOO_PASSWORD":"<YOUR_ODOO_PASSWORD>","ODOO_DB":"<ODOO_DB>","ODOO_URL":"<ODOO_URL>","ODOO_USERNAME":"<ODOO_USERNAME>"}}'Install OdooSurface MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"odoo-surface-mcp": {
"command": "npx",
"args": [
"-y",
"@suco/odoo-surface-mcp"
],
"env": {
"ODOO_PASSWORD": "<YOUR_ODOO_PASSWORD>",
"ODOO_DB": "<ODOO_DB>",
"ODOO_URL": "<ODOO_URL>",
"ODOO_USERNAME": "<ODOO_USERNAME>"
}
}
}
}Install OdooSurface MCP in Codex
$ codex mcp add odoo-surface-mcp --env 'ODOO_PASSWORD=<YOUR_ODOO_PASSWORD>' --env 'ODOO_DB=<ODOO_DB>' --env 'ODOO_URL=<ODOO_URL>' --env 'ODOO_USERNAME=<ODOO_USERNAME>' -- npx -y @suco/odoo-surface-mcpInstall OdooSurface MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.odoo-surface-mcp] command = "npx" args = ["-y", "@suco/odoo-surface-mcp"] [mcp_servers.odoo-surface-mcp.env] ODOO_PASSWORD = "<YOUR_ODOO_PASSWORD>" ODOO_DB = "<ODOO_DB>" ODOO_URL = "<ODOO_URL>" ODOO_USERNAME = "<ODOO_USERNAME>"
Install OdooSurface MCP in Gemini CLI
$ gemini mcp add -s user -e 'ODOO_PASSWORD=<YOUR_ODOO_PASSWORD>' -e 'ODOO_DB=<ODOO_DB>' -e 'ODOO_URL=<ODOO_URL>' -e 'ODOO_USERNAME=<ODOO_USERNAME>' odoo-surface-mcp npx -- -y @suco/odoo-surface-mcpInstall OdooSurface MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"odoo-surface-mcp": {
"command": "npx",
"args": [
"-y",
"@suco/odoo-surface-mcp"
],
"env": {
"ODOO_PASSWORD": "<YOUR_ODOO_PASSWORD>",
"ODOO_DB": "<ODOO_DB>",
"ODOO_URL": "<ODOO_URL>",
"ODOO_USERNAME": "<ODOO_USERNAME>"
}
}
}
}Configuration
ODOO_PASSWORDRequiredSecretOdoo login password
ODOO_DBRequiredOdoo database name
ODOO_URLRequiredOdoo instance URL (e.g. https://myodoo.com)
ODOO_USERNAMERequiredOdoo login username
ODOO_USER
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablesolutionsunity/odoo-surface-mcp is public and reachablegithub.com/solutionsunity/odoo-surface-mcp ↗Pass
- Package names this repository as its source@suco/odoo-surface-mcp names solutionsunity/odoo-surface-mcp as sourcenpmjs.com/package/@suco/odoo-surface-mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @suco/odoo-surface-mcpnpmjs.com/package/@suco/odoo-surface-mcp/v/0.6.1#provenance ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-03github.com/solutionsunity/odoo-surface-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @suco/odoo-surface-mcpPass
- No critical advisory in the package or its dependencies103 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubOdooSurface 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.
- Log in as the user the MCP will authenticate as
- Click the user avatar (top-right) → Preferences
- Go to the Account Security tab
- Under API Keys → click New API Key
- Enter your password when prompted, give the key a name, copy the generated key
- 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
.envfile approach (Option A) does not work for multi-instance setups — both processes share the same working directory and would load the same file. Use theenvblock 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.
OdooSurface MCP questions
How do I add OdooSurface MCP to Claude Code?
Run claude mcp add --env 'ODOO_PASSWORD=<YOUR_ODOO_PASSWORD>' --env 'ODOO_DB=<ODOO_DB>' --env 'ODOO_URL=<ODOO_URL>' --env 'ODOO_USERNAME=<ODOO_USERNAME>' odoo-surface-mcp -- npx -y @suco/odoo-surface-mcp in your terminal. Add --scope user to make it available in every project.
How do I add OdooSurface MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What version of Odoo is supported?
The server supports Odoo version 15.0 and above, including both Community Edition (CE) and Enterprise Edition (EE).
How can I use API keys instead of a password?
Users can generate personal API keys in their Odoo account under Preferences > Account Security. Using these keys as the ODOO_PASSWORD is the recommended method as it avoids storing the actual account password.
Can I connect to multiple Odoo instances at once?
Yes, you can configure multiple named entries in your MCP client config, allowing them to run as independent processes with isolated credentials.