Odoo MCP Server (Standalone)

MCP server độc lập cho phép kết nối với bất kỳ Odoo instance nào qua XML-RPC.

Tính năng

• Multiple Odoo instances - Kết nối động đến nhiều Odoo instances khác nhau
• Connection params per tool call - Truyền thông tin kết nối (URL, DB, credentials) khi gọi tool
• Backward compatible - Vẫn hỗ trợ cấu hình qua .env cho người dùng cũ
• Guardrails - Validate input schema, timeout/retry, allowlist models

Tools

| Tool | Mô tả | |------|-------| | odoo_auth_test | Kiểm tra kết nối và xác thực với connection params | | odoo_search_read | search_read với connection, domain, fields, limit, offset, order | | odoo_read | read bản ghi theo ids | | odoo_create | create bản ghi mới | | odoo_write | write (cập nhật) bản ghi | | odoo_call_method | Gọi method bất kỳ trên model | | odoo_execute_kw_raw | Low-level execute_kw (cần xác nhận rủi ro) |

Cách sử dụng

Mode 1: Truyền connection params khi gọi tool (Khuyến nghị)

Mỗi tool call sẽ truyền thông tin kết nối:

{
  "odooUrl": "http://localhost:8069",
  "db": "odoo19",
  "username": "admin",
  "password": "admin"
  // hoặc dùng "apiKey" thay cho "password"
}

Ví dụ gọi odoo_search_read:

{
  "connection": {
    "odooUrl": "http://localhost:8069",
    "db": "odoo19",
    "username": "admin",
    "password": "admin",
    "allowedModels": "res.partner,project.task",
    "timeoutMs": 10000,
    "retryCount": 1
  },
  "model": "project.task",
  "domain": [["active", "=", true]],
  "fields": ["id", "name", "stage_id"],
  "limit": 20,
  "order": "id desc"
}

Mode 2: Cấu hình qua .env (Backward compatible)

1. Copy file env mẫu:

cp .env.example .env

2. Điền các biến bắt buộc:

ODOO_URL=http://localhost:8069
ODOO_DB=odoo19
ODOO_USERNAME=admin
ODOO_PASSWORD=admin
# Hoặc dùng API key:
# ODOO_API_KEY=your_api_key

# Optional: giới hạn model được phép thao tác
# ODOO_ALLOWED_MODELS=res.partner,project.task,project.project

# Optional guardrails
ODOO_RPC_TIMEOUT_MS=10000
ODOO_RPC_RETRY_COUNT=1

Yêu cầu

• Node.js 20+
• Odoo instance hỗ trợ XML-RPC (/xmlrpc/2/common, /xmlrpc/2/object)

Cài đặt & Chạy

# Install dependencies
npm install

# Build
npm run build

# Start server
npm start

# Dev mode (với hot reload)
npm run dev

# Verify kết nối với .env config
npm run verify

MCP Client Config

Cursor / Claude Desktop

{
  "mcpServers": {
    "odoo": {
      "command": "node",
      "args": ["/ABS_PATH/tools/odoo-mcp-server/dist/index.js"],
      "env": {}
    }
  }
}

Lưu ý: Không cần truyền env credentials nữa - mỗi tool call sẽ truyền connection params.

Ví dụ gọi tools

1. odoo_auth_test - Test kết nối

{
  "odooUrl": "http://localhost:8069",
  "db": "odoo19",
  "username": "admin",
  "password": "admin"
}

Response:

{
  "ok": true,
  "message": "Kết nối thành công",
  "connection": {
    "odooUrl": "http://localhost:8069",
    "db": "odoo19",
    "username": "admin"
  },
  "uid": 2
}

2. odoo_search_read

{
  "connection": {
    "odooUrl": "http://localhost:8069",
    "db": "odoo19",
    "username": "admin",
    "password": "admin"
  },
  "model": "project.task",
  "domain": [["active", "=", true]],
  "fields": ["id", "name", "stage_id"],
  "limit": 20,
  "offset": 0,
  "order": "id desc"
}

3. odoo_read

{
  "connection": {
    "odooUrl": "http://localhost:8069",
    "db": "odoo19",
    "username": "admin",
    "password": "admin"
  },
  "model": "project.task",
  "ids": [1, 2, 3],
  "fields": ["id", "name", "user_ids"]
}

4. odoo_create

{
  "connection": {
    "odooUrl": "http://localhost:8069",
    "db": "odoo19",
    "username": "admin",
    "password": "admin"
  },
  "model": "project.task",
  "values": {
    "name": "Task from MCP"
  }
}

5. odoo_write

{
  "connection": {
    "odooUrl": "http://localhost:8069",
    "db": "odoo19",
    "username": "admin",
    "password": "admin"
  },
  "model": "project.task",
  "ids": [10],
  "values": {
    "name": "Renamed by MCP"
  }
}

6. odoo_call_method

{
  "connection": {
    "odooUrl": "http://localhost:8069",
    "db": "odoo19",
    "username": "admin",
    "password": "admin"
  },
  "model": "project.task",
  "method": "action_archive",
  "ids": [10]
}

7. odoo_execute_kw_raw (cẩn trọng)

{
  "connection": {
    "odooUrl": "http://localhost:8069",
    "db": "odoo19",
    "username": "admin",
    "password": "admin"
  },
  "warning_acknowledged": true,
  "model": "res.partner",
  "method": "search_read",
  "args": [[["is_company", "=", true]]],
  "kwargs": {
    "fields": ["id", "name"],
    "limit": 5
  }
}

Kết nối nhiều Odoo instances

Server hỗ trợ kết nối đến bất kỳ Odoo instance nào. Chỉ cần truyền connection params khác nhau:

// Instance 1: Odoo 19 local
{
  "connection": {
    "odooUrl": "http://localhost:8069",
    "db": "odoo19",
    "username": "admin",
    "password": "admin"
  },
  ...
}

// Instance 2: Odoo 17 production
{
  "connection": {
    "odooUrl": "https://odoo.company.com",
    "db": "prod_db",
    "username": "api_user",
    "apiKey": "xxx_api_key_xxx"
  },
  ...
}

// Instance 3: Odoo.sh
{
  "connection": {
    "odooUrl": "https://my-project.odoo.sh",
    "db": "odoo",
    "username": "admin",
    "password": "admin"
  },
  ...
}

Connection Params Schema

{
  odooUrl: string;              // URL Odoo instance (bắt buộc)
  db: string;                   // Database name (bắt buộc)
  username: string;             // Username/email (bắt buộc)
  password?: string;            // Mật khẩu (1 trong 2: password hoặc apiKey)
  apiKey?: string;              // API Key (1 trong 2: password hoặc apiKey)
  allowedModels?: string;       // Comma-separated list (optional)
  timeoutMs?: number;           // RPC timeout, default 10000
  retryCount?: number;          // Retry count, default 1
}

Bảo mật

• Khuyến nghị dùng API Key thay vì mật khẩu
• Bật allowedModels để giới hạn models được phép thao tác
• odoo_execute_kw_raw có thể thực thi thao tác mạnh; chỉ dùng khi cần
• Secrets được mask trong logs

Guardrails

• Validate input schema bằng zod cho từng tool
• Timeout/retry configurable qua params
• Allowlist model qua allowedModels (optional)
• Mask secrets trong logs (password, apiKey, token...)

Kiến trúc

┌─────────────────┐
│  MCP Client     │
│  (Cursor/Claude)│
└────────┬────────┘
         │
         │  Tool call với connection params
         ▼
┌─────────────────────────────────────────┐
│  odoo-mcp-server (Standalone)           │
│  - Nhận connection params từ client     │
│  - Tạo OdooClient cho mỗi instance      │
│  - Validate & Execute RPC               │
└────────┬────────────────────────────────┘
         │
         │  XML-RPC
         ▼
┌─────────────────────────────────────────┐
│  Odoo Instance (bất kỳ version nào)     │
│  - Odoo 15, 16, 17, 18, 19...           │
│  - Local, Production, Odoo.sh...        │
└─────────────────────────────────────────┘

Troubleshooting

Lỗi "Authenticate thất bại"

• Kiểm tra lại username/password hoặc API key
• Đảm bảo user có quyền access database

Lỗi "RPC timeout"

• Tăng timeoutMs trong connection params
• Kiểm tra kết nối mạng đến Odoo instance

Lỗi "Model không nằm trong allowedModels"

• Thêm model vào allowedModels (comma-separated)
• Hoặc bỏ qua params allowedModels để allow tất cả