Odoo Mcp Gateway

odoo-mcp-gateway

Security-first, version-agnostic MCP gateway for Odoo 17/18/19. Works with stock and custom modules via YAML configuration. Zero Odoo-side code required.

[Python 3.10+] [License: MIT] [Odoo] [Tests] [Coverage]

30-Second Quick Start

pip install odoo-mcp-gateway

Add to Claude Desktop config (claude_desktop_config.json):

{  "mcpServers": {    "odoo": {      "command": "python",      "args": ["-m", "odoo_mcp_gateway"],      "env": {        "ODOO_URL": "http://localhost:8069",        "ODOO_DB": "your_database"      }    }  }}

Restart Claude Desktop. In any conversation:

login with method "password", username "admin", credential "your_password"

You're connected. Ask Claude to query, create, or update Odoo records — every call is rate-limited, audit-logged, and runs through two layers of security checks before reaching Odoo.

No Odoo addon required. No Python code to write. Just YAML config for fine-grained access control (optional — secure defaults work out of the box).

What's New in v0.2.1

• Brute-force protection — per-username (5/5min) + per-source (30/15min) lockout
• dry_run mode on create_record, update_record, delete_record, execute_method — validate without executing
• 2 new tools: get_defaults (preview Odoo defaults), get_onchange (preview field side effects)
• Temporal grouping in read_group: create_date:month, date:quarter, etc.
• Hardened blocklists: 32 always-blocked models (was 17), 29 always-blocked methods (was 18), 10 always-blocked write fields, 8 always read-only models
• Server-side admin verification via has_group('base.group_system') (was trusted from auth response)
• Credential wrapper prevents password leakage via repr()/traceback
• JSON-RPC retry only fires on OdooSessionExpiredError (was retrying on every auth error)

See CHANGELOG.md for the full list of 21 security fixes.

Why This Exists

Existing Odoo MCP servers share common problems: hardcoded model lists that miss custom modules, security as an afterthought, mandatory custom Odoo addons, and single-version targets. This gateway solves all of them:

• Two-layer security — MCP restrictions (YAML) + Odoo's built-in ACLs (ir.model.access + ir.rule)
• YAML-driven configuration — model restrictions, RBAC, field-level access, rate limiting, audit logging
• Custom module support — auto-discovers models via ir.model, add YAML config and it works
• Version-agnostic — Odoo 17, 18, 19 with version-specific adapters
• Zero Odoo-side code — pip install + YAML config = done. No custom addon required
• Full MCP primitives — 31 Tools + 6 Resources + 12 Prompts (most servers only implement Tools)
• Plugin architecture — extend with pip-installable domain packs via entry_points

Architecture

MCP Client (Claude Desktop / Claude Code / HTTP)    |  User calls login tool with Odoo credentials    vMCP Server (FastMCP)    |    |-- security_gate()    --> Rate limit + RBAC tool access + audit logging    |-- restrictions       --> Model/method/field block lists (YAML + hardcoded)    |-- rbac               --> Field-level filtering + write sanitization    |    |-- tools/             --> 31 MCP tools (auth + schema + CRUD + workflow + plugins)    |-- resources/         --> 6 MCP resources (odoo:// URIs)    |-- prompts/           --> 12 reusable prompt templates    |-- plugins/           --> Entry-point plugin system (HR, Sales, Project, Helpdesk)    |    |  JSON-RPC / XML-RPC as authenticated user    vOdoo 17/18/19 (security enforced per user via ir.model.access + ir.rule)

Security Pipeline

Every tool and resource call passes through this pipeline:

Request --> Rate Limit --> Authentication Check --> RBAC Tool Access    --> Model Restriction --> Method Restriction --> Field Validation    --> Handler Execution --> RBAC Field Filtering --> Audit Log --> Response

Hardcoded safety guardrails that cannot be overridden by YAML:

• 32 always-blocked models — system internals, auth/TOTP, payment tokens, attachments, mail.mail, base.automation, and more
• 8 always read-only models — mail.message, mail.followers, mail.activity, discuss.channel, mail.notification, mail.compose.message, mail.alias, discuss.channel.member (reads OK, writes blocked for everyone)
• 10 always-blocked write fields — password, password_crypt, groups_id, totp_secret, signup_token/type/expiration, api_key, share, active
• 29 always-blocked methods — sudo, with_user/env/context, _sql, _write, _create, name_create, load, import_data, export_data, and more
• 28 ORM methods blocked in execute_method (prevents bypassing field-level checks)
• Per-username brute-force lockout — 5 failures → 5 minute lockout (fixed duration, cannot be extended)
• Per-source brute-force lockout — 30 failures / 15 min, prevents username-rotation attacks
• Credential wrapper class — passwords stored with leak-safe __repr__/__str__, cleared on close
• Server-side admin verification — has_group('base.group_system') overrides auth-response is_admin

Quick Start

pip install odoo-mcp-gateway
# Copy and edit config filescp config/restrictions.yaml.example config/restrictions.yamlcp config/model_access.yaml.example config/model_access.yamlcp config/rbac.yaml.example config/rbac.yaml
# Set environment variablesexport ODOO_URL=http://localhost:8069export ODOO_DB=mydb
# Run (stdio mode for Claude Desktop / Claude Code)python -m odoo_mcp_gateway
# Or HTTP mode for web clientsMCP_TRANSPORT=streamable-http python -m odoo_mcp_gateway

Claude Desktop Configuration

Add to claude_desktop_config.json:

{  "mcpServers": {    "odoo": {      "command": "python",      "args": ["-m", "odoo_mcp_gateway"],      "env": {        "ODOO_URL": "http://localhost:8069",        "ODOO_DB": "mydb"      }    }  }}

Claude Code Configuration

# Add as MCP serverclaude mcp add odoo -- python -m odoo_mcp_gateway

Environment Variables

Security

Two-Layer Security Model

1. MCP gateway restrictions (YAML config + hardcoded guardrails) — blocks sensitive models, dangerous methods, privileged fields before any Odoo call is made
2. Odoo's built-in ACLs — enforces per-user access on actual records via ir.model.access and ir.rule

Model Restriction Tiers

Hardcoded Safety Guardrails

These cannot be overridden by YAML configuration:

Blocked models (32): ir.config_parameter, res.users, res.users.apikeys, res.users.log, ir.cron, ir.module.module, ir.model.access, ir.rule, ir.mail_server, ir.ui.view, ir.actions.server, ir.logging, ir.attachment, ir.exports, ir.exports.line, iap.account, auth.totp.wizard, auth.totp.device, payment.token, payment.provider, base.automation, digest.digest, res.config.settings, change.password.wizard, change.password.user, base.module.update, base.module.upgrade, base.module.uninstall, fetchmail.server, bus.bus, mail.mail, mail.template

Read-only models (8): mail.message, mail.followers, mail.activity, discuss.channel, mail.notification, mail.compose.message, mail.alias, discuss.channel.member (reads allowed, writes blocked for everyone)

Blocked write fields (10): password, password_crypt, groups_id, totp_secret, signup_token, signup_type, signup_expiration, api_key, share, active

Blocked methods (29): sudo, with_user, with_company, with_context, with_env, with_prefetch, _auto_init, _sql, _register_hook, _write, _create, _read, _setup_base, _setup_fields, _setup_complete, init, _table_query, _read_group_raw, name_create, load, import_data, export_data, flush_recordset, invalidate_recordset, _search_panel_select_range, _search_panel_select_multi_range, _search_panel_domain_image, _search, _read_progress_bar

Additional Security Features

• Brute-force protection — per-username lockout (5 fails → 5 min) AND per-source IP/connection lockout (30 fails → 15 min, blocks username-rotation attacks). Lockouts have fixed duration — cannot be extended by additional attempts (DoS-resistant).
• Credential wrapper — passwords/session IDs stored in a Credential class with leak-safe __repr__/__str__, explicit .reveal() for use, and .clear() on close
• Server-side admin verification — is_admin is re-verified via has_group('base.group_system') after authentication, defending against tampered auth responses
• Private method guard — underscore-prefixed methods (_compute_*, _inverse_*, etc.) blocked for everyone including admin unless explicitly whitelisted
• Rate limiting — per-session token bucket with separate global and write budgets
• RBAC — tool-level access control by user group, field-level response filtering, transparent drop reporting via return_dropped=True
• Input validation — model names, method names, field names, domain filters, ORDER BY clauses, groupby with temporal operators, write values (size/depth/type)
• IDOR protection — plugin tools scope data access to the authenticated user
• Audit logging — structured JSON logs for all allowed and denied operations
• Error sanitization — strips internal URLs, SQL fragments, file paths, stack traces from error messages
• XXE protection — XML-RPC responses parsed with defusedxml
• Domain validation — Odoo domain filters validated for operators, field names, value types, nesting depth, and list sizes
• Session-expiry retry — JSON-RPC retries only on OdooSessionExpiredError, not generic auth errors (no double round-trips on access denials)

Authentication

Three stock Odoo auth methods — no custom addon needed:

# Example: login via the MCP tool> login(method="password", username="admin", credential="admin", database="mydb")

Core MCP Tools (13)

Workflow Tools (2)

MCP Resources (6)

MCP Prompts (12)

Built-in Domain Plugins

HR Plugin

Sales Plugin

Project Plugin

Helpdesk Plugin

Custom Module Support

Add custom Odoo modules without writing Python code. Edit model_access.yaml:

custom_models:  full_crud:    - custom.delivery.route    - custom.warehouse.zone  read_only:    - custom.delivery.log
allowed_methods:  custom.delivery.route:    - action_dispatch    - action_complete    - action_cancel

Then all CRUD tools (search_read, create_record, update_record, delete_record) and execute_method work on the custom models with full security enforcement.

Plugin System

Extend the gateway with pip-installable plugins:

from odoo_mcp_gateway.plugins.base import OdooPlugin
class ManufacturingPlugin(OdooPlugin):    @property    def name(self) -> str:        return "manufacturing"
    @property    def required_odoo_modules(self) -> list[str]:        return ["mrp"]
    @property    def required_models(self) -> list[str]:        return ["mrp.production", "mrp.bom"]
    def register(self, server, context):        @server.tool()        async def get_production_orders(...):            ...

Register via pyproject.toml entry points:

[project.entry-points."odoo_mcp_gateway.plugins"]manufacturing = "my_package:ManufacturingPlugin"

Configuration Files

All files have .example templates with extensive inline documentation. Copy and customize:

cp config/restrictions.yaml.example config/restrictions.yamlcp config/model_access.yaml.example config/model_access.yamlcp config/rbac.yaml.example config/rbac.yaml

Example: Restrict a Model

# restrictions.yamlrestrictions:  always_blocked:    - my.secret.model  admin_only:    - hr.salary.rule  admin_write_only:    - res.company  blocked_write_fields:    - password_crypt    - api_key    - totp_secret

Example: RBAC by Group

# rbac.yamlrbac:  tool_group_requirements:    delete_record:      - base.group_system    execute_method:      - base.group_erp_manager  sensitive_fields:    hr.employee:      salary:        required_group: hr.group_hr_manager

Docker

cp .env.example .env   # Edit with your Odoo settingsdocker compose up

Services:

• MCP Gateway — port 8080 (streamable-http mode)
• Odoo 18 — internal only (no host port exposed by default)
• PostgreSQL — internal only

The gateway runs as a non-root user in a minimal Python image.

CLI Tools

# Test Odoo connectivityodoo-mcp-tools test-connection --url http://localhost:8069
# Validate all YAML config filesodoo-mcp-tools validate-config --config-dir config
# List configured model access policiesodoo-mcp-tools list-models --config-dir config

Development

git clone https://github.com/parth-unjiya/odoo-mcp-gateway.gitcd odoo-mcp-gatewaypip install -e ".[dev]"
# Run testspytest tests/ -v
# Run with coveragepytest tests/ --cov=odoo_mcp_gateway --cov-report=term-missing
# Lintruff check src/ tests/
# Type check (strict mode)mypy src/

Source Layout

src/odoo_mcp_gateway/├── __main__.py                  # Entry point (stdio + HTTP)├── server.py                    # FastMCP server setup, tool registration├── config.py                    # Pydantic settings (env + .env)├── client/│   ├── base.py                  # OdooClientBase ABC, AuthResult│   ├── jsonrpc.py               # JSON-RPC client (session auth)│   ├── xmlrpc.py                # XML-RPC client (API key auth, defusedxml)│   └── exceptions.py            # OdooError hierarchy (7 types)├── core/│   ├── auth/manager.py          # 3 auth strategies│   ├── connection/manager.py    # Circuit breaker + retry│   ├── version/                 # Odoo 17/18/19 detection + adapters│   ├── workflow/│   │   ├── definitions.py      # WorkflowDef, StateDef, TransitionDef dataclasses│   │   ├── registry.py         # Workflow registration and lookup│   │   └── stock_workflows/    # Built-in workflows (sale, purchase, HR, etc.)│   ├── security/│   │   ├── restrictions.py      # 3-tier model/method restrictions + hardcoded guardrails│   │   ├── rbac.py              # Tool access + field filtering│   │   ├── middleware.py        # Security pipeline + security_gate()│   │   ├── rate_limit.py        # Token bucket rate limiter│   │   ├── audit.py             # Structured audit logging│   │   ├── sanitizer.py         # Error message sanitization│   │   └── config_loader.py     # YAML config → Pydantic models│   └── discovery/│       ├── model_registry.py    # ir.model auto-discovery│       ├── field_inspector.py   # fields_get with TTL cache│       └── suggestions.py       # Category search + related models├── tools/│   ├── auth.py                  # login tool│   ├── schema.py                # list_models, get_model_fields│   ├── crud.py                  # search_read, create/update/delete, execute_method│   └── workflow.py              # get_create_requirements, get_record_actions├── resources/handlers.py        # 6 MCP resources (odoo:// URIs)├── prompts/handlers.py          # 12 MCP prompt templates├── plugins/│   ├── base.py, registry.py     # Plugin ABC + entry_point discovery│   └── core/                    # Built-in plugins (HR, Sales, Project, Helpdesk)├── cli/tools.py                 # CLI: test-connection, validate-config└── utils/                       # Domain builder, formatting, token budget

Testing

1,476 tests passing, 93% code coverage, mypy strict clean, ruff clean:

tests/unit/├── client/          # JSON-RPC, XML-RPC, auth manager, XXE protection├── security/        # Restrictions, RBAC, audit, rate limit, sanitizer, security_gate├── discovery/       # Model registry, field inspector, suggestions├── tools/           # All 13 MCP tools + input validation + dry_run├── plugins/         # Plugin system + 4 domain plugins + IDOR protection└── cli/             # CLI utility tools

# Run all testspytest tests/ -v
# Run specific areapytest tests/unit/security/ -vpytest tests/unit/tools/ -vpytest tests/unit/plugins/ -v
# Coverage reportpytest tests/ --cov=odoo_mcp_gateway --cov-report=html

Error Handling

All Odoo errors are classified into 7 types:

All error messages are sanitized before reaching the MCP client — internal URLs, SQL fragments, file paths, and stack traces are automatically stripped.

Known Limitations

• XML-RPC credential handling: When using API key authentication (XML-RPC), the credential is sent with every RPC call as required by the protocol. Use HTTPS in production. (Note: passwords are stored in a Credential wrapper that prevents repr()/traceback leakage.)
• HTTP mode session isolation: streamable-http transport currently has known session isolation limitations — the _current_session_key ContextVar is set inside the login tool but subsequent tool calls from different request contexts may fall back to the first available session. Deploy HTTP mode as single-tenant only (one user per server process) until per-request middleware lands in v0.3.0. stdio mode is single-session by design and unaffected.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes with tests
4. Ensure all checks pass: pytest && ruff check src/ tests/ && mypy src/
5. Submit a pull request

License

MIT