{
  "markdown": "# OdooSurface MCP\n\n[![npm version](https://img.shields.io/npm/v/@suco/odoo-surface-mcp)](https://www.npmjs.com/package/@suco/odoo-surface-mcp)\n[![Node](https://img.shields.io/node/v/@suco/odoo-surface-mcp)](https://www.npmjs.com/package/@suco/odoo-surface-mcp)\n[![Odoo](https://img.shields.io/badge/Odoo-17%2B-blueviolet)](https://www.odoo.com)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Downloads](https://img.shields.io/npm/dm/@suco/odoo-surface-mcp)](https://www.npmjs.com/package/@suco/odoo-surface-mcp)\n\nUser-equivalent Odoo access for AI agents — what the authenticated user can do in their browser, nothing more.\n\n## Prerequisites\n\n- Node.js 18+ (ships with `npx` — no extra install needed)\n- A running Odoo instance (17.0+, CE or EE)\n- An MCP-compatible client (VS Code, Claude Desktop, Claude Code, Cursor, …)\n\n## Configure your MCP client\n\nAdd this to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"odoo-surface\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@suco/odoo-surface-mcp@latest\"],\n      \"env\": {\n        \"ODOO_URL\": \"http://localhost:8069\",\n        \"ODOO_DB\": \"your_database\",\n        \"ODOO_USER\": \"admin\",\n        \"ODOO_PASSWORD\": \"admin\"\n      }\n    }\n  }\n}\n```\n\nRestart your MCP client after saving. `npx` downloads and runs the package automatically — no further install steps.\n\n## Authentication\n\n### Option A — `.env` file (keep credentials out of MCP config)\n\nInstead of putting credentials in your MCP client JSON, create a `.env` file in the directory where you run the MCP:\n\n```ini\nODOO_URL=http://localhost:8069\nODOO_DB=your_database\nODOO_USER=admin\nODOO_PASSWORD=your_password\n```\n\nRemove the `env` block from the MCP client config — the `.env` file is loaded automatically.\n\n### Option B — API Key (recommended, no password stored)\n\nSince Odoo 14+, users can generate personal API keys that act as a password replacement.\nEach user generates their own key from their own account — there is no admin-side menu for this.\n\n1. Log in as the user the MCP will authenticate as\n2. Click the **user avatar** (top-right) → **Preferences**\n3. Go to the **Account Security** tab\n4. Under **API Keys** → click **New API Key**\n5. Enter your password when prompted, give the key a name, copy the generated key\n6. Use it as `ODOO_PASSWORD` — the actual account password is never stored\n\n```ini\nODOO_URL=http://localhost:8069\nODOO_DB=your_database\nODOO_USER=admin\nODOO_PASSWORD=your_api_key_here\n```\n\nAPI keys can be revoked individually from the same screen without changing the account password.\n\n## Advanced Configuration\n\n### Multiple Odoo instances\n\nTechnical users commonly work with more than one Odoo instance (local dev, staging, production).\nEach instance gets its own named entry in the MCP config — they run as independent processes with\nfully isolated credentials. The AI client exposes them as separate tool namespaces.\n\n```json\n{\n  \"mcpServers\": {\n    \"odoo-local\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@suco/odoo-surface-mcp@latest\"],\n      \"env\": {\n        \"ODOO_URL\": \"http://localhost:8069\",\n        \"ODOO_DB\": \"dev\",\n        \"ODOO_USER\": \"admin\",\n        \"ODOO_PASSWORD\": \"dev_api_key\"\n      }\n    },\n    \"odoo-production\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@suco/odoo-surface-mcp@latest\"],\n      \"env\": {\n        \"ODOO_URL\": \"https://mycompany.odoo.com\",\n        \"ODOO_DB\": \"prod\",\n        \"ODOO_USER\": \"admin\",\n        \"ODOO_PASSWORD\": \"prod_api_key\"\n      }\n    }\n  }\n}\n```\n\n> **Note:** The `.env` file approach (Option A) does not work for multi-instance setups — both\n> processes share the same working directory and would load the same file. Use the `env` block\n> per entry instead.\n\n## Debug mode\n\nRegisters additional tools: `ping`, `echo`, `inspect_view`, `inspect_action`, `inspect_fields`, `dump_cache`, `clear_cache`, `restart_mcp`.\n\n```json\n\"args\": [\"-y\", \"@suco/odoo-surface-mcp@latest\", \"--debug\"]\n```\n\n## Tools\n\n| Layer | Tools |\n|---|---|\n| Guidance | `list_skills`, `get_skills`, `find_skill`, `list_workflows`, `get_workflows` |\n| Discovery | `get_models`, `get_model_actions`, `get_model_interface` |\n| Planning | `get_available_actions` |\n| Supporting | `list_records`, `get_record`, `search_records`, `get_fields`, `get_defaults`, `get_filters`, `list_snippets`, `get_snippet`, `list_attachments`, `fetch_and_upload`, `translation_get`, `translation_update`, `translation_audit` |\n| Intent | `create`, `update`, `execute_action`, `archive`, `post_message`, `schedule_activity`, `set_page_arch`, `set_page_visibility` |\n\n## Architecture\n\n### Core Contract\n\nThe agent may only do what the authenticated user can do in their browser. Scope is bounded by the\nuser's menus, views, and ACL — nothing more. Tool verbs express functional intent (publish, confirm)\nrather than raw ORM operations. Discovery is lazy: the agent resolves only what the current prompt\nrequires.\n\n### Layered Tool Surface\n\n| Layer | Role | When invoked |\n|---|---|---|\n| **0 — Guidance** | Canonical recipes (skills, workflows) the agent consults before any multi-step operation. Pure documentation, no side effects. | Before planning |\n| **1 — Discovery** | Establishes the bounded universe of models and reachable relations for the current user. | At intent resolution |\n| **2 — Planning Bridge** | Answers \"what is live on this specific record right now\" — record-state-aware actions. | Once a record is identified |\n| **3 — Supporting** | Read-only data fetchers used silently to fill gaps in the agent's plan. | Throughout planning |\n| **4 — Intent** | Mutating actions that fulfill the user's request — bounded by the user's UI permissions. | Final execution |\n\n### Planning Loop\n\n```\nUser prompt\n  ├── Discovery       — what models/relations does this user have?\n  ├── (optional)      — locate the specific record\n  ├── Planning Bridge — what is live on that record right now?\n  ├── Guidance        — consult skills/workflows for multi-step recipes\n  └── Intent          — execute the mutation(s)\n```\n\nSkills and workflows are authored in `skills/` and `workflows/` as markdown with YAML\nfrontmatter; they are exposed as Layer 0 tools at runtime.\n",
  "bytes": 6212,
  "sha": "ba480d5d3360db604d3dfb455f7a896ab12fdd0518147000252ccb765f6e275a",
  "repo_slug": "solutionsunity/odoo-surface-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_solutionsunity_odoo_surface_mc_cbe4f82a/readme"
}