🚀 Odoo MCP Server Integration

Expose a Model Context Protocol (MCP) server directly from your Odoo instance—no external services required.

With this module, tools like Claude or Cursor can securely query and manage your Odoo data using natural language.

Key benefits:

• No separate backend process
• Native Odoo integration
• Real-time interaction via SSE
• Full ORM access (read/write)

⚙️ Setup

1. Install the Module

Install the module on your Odoo database like any standard addon.

2. Specify the Database

You can pass the database using one of the following methods:

• URL parameter: ?db=<name>
• Header: X-Odoo-Database
• Authorization: Bearer demo_ai:YOUR_API_KEY

3. Connect with Claude / Cursor

Use mcp-remote with:

• --transport sse-only
• --allow-http

4. Fix 404 Errors

If you encounter a 404 error:

[options]
server_wide_modules = web,rag_odoo_mcp_server

Restart Odoo after applying changes.

💡 Usage Examples

🔍 Data Retrieval

Natural language queries are translated into MCP tool calls:

• “Show me all customers from Spain”
  → odoo_search_read(res.partner, country_id.code = ES)
• “Find products with stock below 10 units”
  → Use product.product or stock.quant
• “List today's sales orders over $1000”
  → Filter sale.order by amount
• “Search for unpaid invoices from last month”
  → Filter account.move by payment state

✏️ Data Management

• “Create a new customer contact for Acme Corporation”
  → odoo_create(res.partner, {...})
• “Add a new product ‘Premium Widget’ with price $99.99”
  → odoo_create(product.product, {...})
• “Update the phone number for John Doe”
  → odoo_search_read → odoo_write
• “Confirm order SO/2024/001”
  → odoo_execute(action_confirm)
• “Delete the test contact”
  → odoo_unlink(...)

🔌 API Endpoints

Method	Endpoint	Description
GET	/mcp/sse?db=<database>	Open SSE stream
POST	/mcp/messages/?session_id=<id>&db=<database>	JSON-RPC calls
GET	/mcp/health?db=<database>	Health check

Authentication (optional):

• Authorization: Bearer <key>
• X-API-Key: <key>

🧰 Available MCP Tools

• list_tables
• describe_table
• get_table_row_count
• run_readonly_query
• get_odoo_models_info
• get_table_schema_pg
• odoo_search_read
• odoo_create
• odoo_write
• odoo_unlink
• odoo_execute

🧪 Standalone Mode (Read-Only)

Run MCP without Odoo ORM:

pip install -r rag_odoo_mcp_server/requirements-mcp.txt
python -m rag_odoo_mcp_server.mcp_server --host 0.0.0.0 --port 8000

SSE Endpoint:

http://<host>:8000/sse

⚠️ ORM methods (create, write, etc.) are not available in this mode.

🏢 Company Context (Optional)

Note: Now handled via UI configuration. Manual setup is kept for reference.

Priority order:

1. Per-tool argument
2. Per-request / session
3. System default

Examples:

• Per-tool: company_id=2
• Request: ?company_id=2 or header
• Session: SSE URL param
• Default: Set in module settings

If unset → all companies are visible.

⚡ Nginx Optimization (Important)

For real-time SSE performance, disable buffering:

location /mcp/ {
    proxy_pass http://your_odoo_backend;
    proxy_buffering off;
    proxy_set_header X-Accel-Buffering no;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
    chunked_transfer_encoding on;
}

👉 Without this, SSE events may be delayed or blocked.

☁️ Odoo.sh Configuration

No need to specify the database:

{
  "mcpServers": {
    "odoo": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://link.dev.odoo.com/odoo/mcp/sse",
        "--allow-http",
        "--transport",
        "sse-only",
        "--header",
        "Authorization:${MCP_CRM_AUTH}"
      ],
      "env": {
        "MCP_CRM_AUTH": "Bearer tokenkey"
      }
    }
  }
}

⚠️ Troubleshooting

Error: HTTP 400 Unknown or expired session

✅ Option 1 (Recommended for VPS)

• SSH into your server
• Set:

workers = 0

• Restart Odoo

✅ Option 2 (Production Setup – Nginx Sticky Sessions)

Use session-based routing:

map $arg_session_id $mcp_sticky {
    default        $remote_addr;
    ~.+            $arg_session_id;
}

upstream odoo_mcp {
    hash $mcp_sticky consistent;
    server 127.0.0.1:8069;
    server 127.0.0.1:8070;
}

Then configure:

location ~ ^/(odoo/)?mcp/ {
    proxy_pass http://odoo_mcp;
    proxy_http_version 1.1;
    proxy_buffering off;
    proxy_read_timeout 1h;
    proxy_send_timeout 1h;
    chunked_transfer_encoding on;
    add_header X-Accel-Buffering no;
}

⚠️ Important Notes

• Odoo workers share ports by default → true sticky routing requires custom setup
• Single-instance deployments benefit most from Option 1
• Always disable buffering for SSE