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.

<!-- mcp-name: io.github.parth-unjiya/odoo-mcp-gateway -->

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
    v
MCP 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
    v
Odoo 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 files
cp config/restrictions.yaml.example config/restrictions.yaml
cp config/model_access.yaml.example config/model_access.yaml
cp config/rbac.yaml.example config/rbac.yaml

# Set environment variables
export ODOO_URL=http://localhost:8069
export ODOO_DB=mydb

# Run (stdio mode for Claude Desktop / Claude Code)
python -m odoo_mcp_gateway

# Or HTTP mode for web clients
MCP_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 server
claude 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.yaml
cp config/model_access.yaml.example config/model_access.yaml
cp config/rbac.yaml.example config/rbac.yaml

Example: Restrict a Model

# restrictions.yaml
restrictions:
  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.yaml
rbac:
  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 settings
docker 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 connectivity
odoo-mcp-tools test-connection --url http://localhost:8069

# Validate all YAML config files
odoo-mcp-tools validate-config --config-dir config

# List configured model access policies
odoo-mcp-tools list-models --config-dir config

Development

git clone https://github.com/parth-unjiya/odoo-mcp-gateway.git
cd odoo-mcp-gateway
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=odoo_mcp_gateway --cov-report=term-missing

# Lint
ruff 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 tests
pytest tests/ -v

# Run specific area
pytest tests/unit/security/ -v
pytest tests/unit/tools/ -v
pytest tests/unit/plugins/ -v

# Coverage report
pytest 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