io.github.nicolasramos/odoo-mcp

OdooClaw MCP

Standalone MCP (Model Context Protocol) server for Odoo 18 over stdio.

MCP name: io.github.nicolasramos/odooclaw-mcp
PyPI package: odooclaw-mcp
Official CLI: odooclaw-mcp

Backward-compatible aliases are also installed:

• odoo-mcp
• odoo-mcp-server
• odoo-18-mcp-server

Quick Start

1) Install

pip install odooclaw-mcp

From source:

git clone https://github.com/nicolasramos/odooclaw-mcp.git
cd odooclaw-mcp
pip install -e .

2) Configure environment

cp .env.example .env

Required:

ODOO_URL=https://yourcompany.odoo.com
ODOO_DB=your_database
ODOO_USERNAME=your_username
ODOO_PASSWORD=your_password

Optional:

ODOO_MCP_DEFAULT_LIMIT=50
ODOO_MCP_MAX_LIMIT=80
LOG_LEVEL=INFO

3) Validate and run

odooclaw-mcp --check-config
odooclaw-mcp

Alternative:

python -m odoo_mcp

MCP Client Configuration (stdio)

{
  "mcpServers": {
    "odoo": {
      "command": "odooclaw-mcp",
      "env": {
        "ODOO_URL": "https://yourcompany.odoo.com",
        "ODOO_DB": "your_database",
        "ODOO_USERNAME": "your_username",
        "ODOO_PASSWORD": "your_password",
        "ODOO_MCP_DEFAULT_LIMIT": "50",
        "ODOO_MCP_MAX_LIMIT": "80"
      }
    }
  }
}

Tool call payload contract

When calling tools through the MCP protocol, arguments must be wrapped in a top-level payload object.

Valid shape:

{
  "name": "odoo_search",
  "arguments": {
    "payload": {
      "model": "res.partner",
      "domain": [["customer_rank", ">", 0]],
      "limit": 3
    }
  }
}

If payload is omitted, validation fails with an error equivalent to Field required: payload.

Scope

• 129 MCP tools for Odoo operations (CRUD + business actions + migration workflows)
• Pydantic validation for all tool payloads
• Odoo 18 compatibility helpers (customer_rank / supplier_rank / payment_state)
• Security guards (model allowlist, denylisted fields, action guard, unlink blocked)
• Structured logging and audit actions

Available Tools

The server currently exposes 129 MCP tools.

Note: the grouped tables below focus on common/high-value tools. Use MCP list_tools to inspect the full live tool catalog for your installed version.

Core record operations

Partners, sales, and CRM

Accounting, purchasing, and payments

Projects, activities, and chatter

Support, contracts, stock, and instance capabilities

Introspection

Available Resources

The server also exposes 5 MCP resources for discovery and context:

Guardrails and Runtime Behavior

• Uses standard Odoo JSON-RPC endpoints; it does not depend on OdooClaw delegation.
• Tool payloads are validated with Pydantic before execution.
• Model access is restricted by an allowlist defined in the server configuration.
• Sensitive write fields are denylisted and unlink is blocked.
• Search-style tools use default and maximum limits (ODOO_MCP_DEFAULT_LIMIT, ODOO_MCP_MAX_LIMIT).
• sender_id is treated as audit/context metadata; execution runs as the authenticated Odoo session user.
• Some tools require the corresponding Odoo apps/modules to be installed (CRM, Helpdesk, Projects, Contracts, Inventory, etc.).

Security Model

The server uses standard Odoo JSON-RPC endpoints and executes operations as the configured Odoo session user.

For production, use a dedicated least-privilege Odoo account.

Production Notes

• This is a stdio MCP server, not an HTTP API service.
• Docker/Compose support is mainly for packaging or controlled runtime scenarios.
• In normal usage, your MCP client launches the server process directly.
• Keep Odoo credentials in environment variables or a secrets manager.

Known Limitations

• One Odoo credential context per MCP process.
• ODOO_DB is currently required by the authentication flow.
• Some tools require specific Odoo apps/modules (CRM, Helpdesk, Project, etc.).
• Designed for Odoo 18 field semantics.

Development

pip install -e .[dev]
ruff check src tests
black --check src tests
mypy src --ignore-missing-imports
pytest tests -v
python -m build
twine check dist/*

Docs

• Architecture
• Deployment
• QA Runbook

License

MIT - see LICENSE.