odoo-mcp-server

Odoo MCP Server

A standalone Model Context Protocol (MCP) server for Odoo, providing Claude with safe, human-approved access to Odoo CRM, projects, and other business domains.

Overview

This MCP server exposes Odoo as a set of modular, domain-specific tools that Claude can safely call:

• Sales & Pre-Sales — CRM pipeline, leads, contacts, solution design
• Project Delivery — Fixed-scope projects, tasks, milestones
• Domain-extensible — Easy to add support for other Odoo apps (Support, Finance, Knowledge, ERP Implementation, etc.)

All write operations are safety-checked to prevent accidental outbound communication (emails, SMS, calendar invites). Internal-only notes, activities, and field updates are safe by design.

Disclaimer

• This project is an independent, community-maintained MCP server and is not affiliated with, endorsed by, or sponsored by Odoo S.A.
• Odoo is a trademark of Odoo S.A. Any product names, logos, and brands are used for identification only.
• You are responsible for validating security, compliance, and access controls before using this server in production environments.
• Always test write-enabled workflows in a non-production environment first.

Key Features

• ✅ Safety-first: Outbound communication blocker prevents emails, SMS, and invites
• ✅ Human-in-the-loop: Write operations require upstream approval (Claude conversation)
• ✅ Multi-company: Supports Odoo's multi-company architecture
• ✅ Per-user credentials: Each Claude user stores their own Odoo API credentials locally
• ✅ Async XML-RPC: Non-blocking Odoo API calls
• ✅ Fully typed: Pydantic validation on all tool inputs
• ✅ Easy deployment: Single pip install entry point

Installation

Via pip

pip install odoo-mcp-server

Via uv (fast Python installer)

uvx --from https://github.com/italanta/odoo-mcp-server odoo-mcp-server

Setup

Setup is centralized in setup.md.

This project supports two hosting modes only:

1. Personal agent hosting on local machines via Claude Desktop, ClawdBot, and Hermes.
2. Org-wide hosting on Claude Cowork via plugin installation from your own fork.

See setup.md for install steps, transport settings, update flow, and security guidance.

Hosted MCP Server Warning

Do not host this package as a shared central MCP server for multiple users.

Odoo access relies on private API tokens. Central hosting would concentrate those tokens in one service, creating unnecessary credential custody and lateral-access risk.

This package is designed to run inside the supported harnesses documented in setup.md, where each user or managed plugin environment controls its own credentials.

Tools

Generic Odoo Tools

• odoo_ping — Validate connectivity and show your profile
• odoo_search_read — Find records with flexible filters
• odoo_read_records — Read specific records by ID
• odoo_log_internal_note — Add internal chatter notes directly (safe)
• odoo_schedule_activity — Build staged payload for an internal reminder activity
• odoo_fields_get — Introspect model field definitions
• odoo_search_count — Count records matching a filter
• odoo_diagnose_call — Diagnose planned model calls without executing them
• odoo_preview_write — Build a canonical non-executing mutation payload
• odoo_validate_write — Validate payload against SafetyGuard and live metadata (when applicable)
• odoo_execute_approved_write — Execute only with token + confirm + env gate
• odoo_setup_credentials — Save/update credentials
• odoo_check_for_update — Check latest GitHub release/tag and suggest update command
• odoo_apply_self_update — Apply local package update (guarded by explicit confirm + env gate)

Write Approval Flow

All mutating operations follow a strict staged approval flow, except internal notes. Internal notes are the only direct mutation endpoint.

1. odoo_preview_write

• Builds a canonical draft payload (model, operation, record_ids, values, method, args, kwargs)
• Does not validate against live Odoo metadata
• Does not execute anything

2. odoo_validate_write

• Applies SafetyGuard policy checks
• Validates payload fields against live fields_get metadata for create/write
• Issues a short-lived, single-use approval_token

3. User approval in conversation

• Claude/Clawdbot must ask for explicit user confirmation before any execution step
• The validated payload must be accepted by the user as-is

4. odoo_execute_approved_write

• Requires confirm=true
• Requires a valid unused token from step 2
• Requires ODOO_MCP_ENABLE_WRITES=1
• Executes only the validated operation (create, write, or call)

Fail-closed behavior:

• Missing confirmation, invalid/expired token, or disabled runtime write gate blocks execution.
• Tokens are single-use and payload-bound; replay and drift attempts are rejected.