An MCP server that enables AI assistants like Claude to interact with Odoo ERP systems. Access business data, search records, create new entries, update existing data, and manage your Odoo instance through natural language. Works with any Odoo instance! Use YOLO mode for quick testing and demos with any standard Odoo installation. For enterprise security, access controls, and production use, insta
Add this skill
npx mdskills install ivnvxd/mcp-server-odooComprehensive Odoo ERP integration with excellent documentation and flexible authentication options
1# MCP Server for Odoo23[](https://github.com/ivnvxd/mcp-server-odoo/actions/workflows/ci.yml)4[](https://codecov.io/gh/ivnvxd/mcp-server-odoo)5[](https://github.com/astral-sh/ruff)6[](https://github.com/astral-sh/ty)7[](https://www.python.org/downloads/)8[](https://opensource.org/licenses/MPL-2.0)910An MCP server that enables AI assistants like Claude to interact with Odoo ERP systems. Access business data, search records, create new entries, update existing data, and manage your Odoo instance through natural language.1112**Works with any Odoo instance!** Use [YOLO mode](#yolo-mode-developmenttesting-only-) for quick testing and demos with any standard Odoo installation. For enterprise security, access controls, and production use, install the [Odoo MCP module](https://apps.odoo.com/apps/modules/19.0/mcp_server).1314## Features1516- 🔍 **Search and retrieve** any Odoo record (customers, products, invoices, etc.)17- ✨ **Create new records** with field validation and permission checks18- ✏️ **Update existing data** with smart field handling19- 🗑️ **Delete records** respecting model-level permissions20- 🔢 **Count records** matching specific criteria21- 📋 **Inspect model fields** to understand data structure22- 🔐 **Secure access** with API key or username/password authentication23- 🎯 **Smart pagination** for large datasets24- 🧠 **Smart field selection** — automatically picks the most relevant fields per model25- 💬 **LLM-optimized output** with hierarchical text formatting26- 🌍 **Multi-language support** — get responses in your preferred language27- 🚀 **YOLO Mode** for quick access with any Odoo instance (no module required)2829## Installation3031### Prerequisites3233- Python 3.10 or higher34- Access to an Odoo instance:35 - **Standard mode** (production): Version 16.0+ with the [Odoo MCP module](https://apps.odoo.com/apps/modules/19.0/mcp_server) installed36 - **YOLO mode** (testing/demos): Any Odoo version with XML-RPC enabled (no module required)3738### Install UV First3940The MCP server runs on your **local computer** (where Claude Desktop is installed), not on your Odoo server. You need to install UV on your local machine:4142<details>43<summary>macOS/Linux</summary>4445```bash46curl -LsSf https://astral.sh/uv/install.sh | sh47```48</details>4950<details>51<summary>Windows</summary>5253```powershell54powershell -c "irm https://astral.sh/uv/install.ps1 | iex"55```56</details>5758After installation, restart your terminal to ensure UV is in your PATH.5960### Installing via MCP Settings (Recommended)6162Add this configuration to your MCP settings:6364```json65{66 "mcpServers": {67 "odoo": {68 "command": "uvx",69 "args": ["mcp-server-odoo"],70 "env": {71 "ODOO_URL": "https://your-odoo-instance.com",72 "ODOO_API_KEY": "your-api-key-here"73 }74 }75 }76}77```7879<details>80<summary>Claude Desktop</summary>8182Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:8384```json85{86 "mcpServers": {87 "odoo": {88 "command": "uvx",89 "args": ["mcp-server-odoo"],90 "env": {91 "ODOO_URL": "https://your-odoo-instance.com",92 "ODOO_API_KEY": "your-api-key-here",93 "ODOO_DB": "your-database-name"94 }95 }96 }97}98```99</details>100101<details>102<summary>Claude Code</summary>103104Add to `.mcp.json` in your project root:105106```json107{108 "mcpServers": {109 "odoo": {110 "command": "uvx",111 "args": ["mcp-server-odoo"],112 "env": {113 "ODOO_URL": "https://your-odoo-instance.com",114 "ODOO_API_KEY": "your-api-key-here",115 "ODOO_DB": "your-database-name"116 }117 }118 }119}120```121122Or use the CLI:123124```bash125claude mcp add odoo \126 --env ODOO_URL=https://your-odoo-instance.com \127 --env ODOO_API_KEY=your-api-key-here \128 --env ODOO_DB=your-database-name \129 -- uvx mcp-server-odoo130```131</details>132133<details>134<summary>Cursor</summary>135136Add to `~/.cursor/mcp.json`:137138```json139{140 "mcpServers": {141 "odoo": {142 "command": "uvx",143 "args": ["mcp-server-odoo"],144 "env": {145 "ODOO_URL": "https://your-odoo-instance.com",146 "ODOO_API_KEY": "your-api-key-here",147 "ODOO_DB": "your-database-name"148 }149 }150 }151}152```153</details>154155<details>156<summary>VS Code (with GitHub Copilot)</summary>157158Add to `.vscode/mcp.json` in your workspace:159160```json161{162 "servers": {163 "odoo": {164 "type": "stdio",165 "command": "uvx",166 "args": ["mcp-server-odoo"],167 "env": {168 "ODOO_URL": "https://your-odoo-instance.com",169 "ODOO_API_KEY": "your-api-key-here",170 "ODOO_DB": "your-database-name"171 }172 }173 }174}175```176177> **Note:** VS Code uses `"servers"` as the root key, not `"mcpServers"`.178</details>179180<details>181<summary>Windsurf</summary>182183Add to `~/.codeium/windsurf/mcp_config.json`:184185```json186{187 "mcpServers": {188 "odoo": {189 "command": "uvx",190 "args": ["mcp-server-odoo"],191 "env": {192 "ODOO_URL": "https://your-odoo-instance.com",193 "ODOO_API_KEY": "your-api-key-here",194 "ODOO_DB": "your-database-name"195 }196 }197 }198}199```200</details>201202<details>203<summary>Zed</summary>204205Add to `~/.config/zed/settings.json`:206207```json208{209 "context_servers": {210 "odoo": {211 "command": {212 "path": "uvx",213 "args": ["mcp-server-odoo"],214 "env": {215 "ODOO_URL": "https://your-odoo-instance.com",216 "ODOO_API_KEY": "your-api-key-here",217 "ODOO_DB": "your-database-name"218 }219 }220 }221 }222}223```224</details>225226### Alternative Installation Methods227228<details>229<summary>Using Docker</summary>230231Run with Docker — no Python installation required:232233```json234{235 "mcpServers": {236 "odoo": {237 "command": "docker",238 "args": [239 "run", "-i", "--rm",240 "-e", "ODOO_URL=http://host.docker.internal:8069",241 "-e", "ODOO_API_KEY=your-api-key-here",242 "ivnvxd/mcp-server-odoo"243 ]244 }245 }246}247```248249> **Note:** Use `host.docker.internal` instead of `localhost` to connect to Odoo running on the host machine.250251For HTTP transport:252253```bash254docker run --rm -p 8000:8000 \255 -e ODOO_URL=http://host.docker.internal:8069 \256 -e ODOO_API_KEY=your-api-key-here \257 ivnvxd/mcp-server-odoo --transport streamable-http --host 0.0.0.0258```259260The image is also available on GHCR: `ghcr.io/ivnvxd/mcp-server-odoo`261</details>262263<details>264<summary>Using pip</summary>265266```bash267# Install globally268pip install mcp-server-odoo269270# Or use pipx for isolated environment271pipx install mcp-server-odoo272```273274Then use `mcp-server-odoo` as the command in your MCP configuration.275</details>276277<details>278<summary>From source</summary>279280```bash281git clone https://github.com/ivnvxd/mcp-server-odoo.git282cd mcp-server-odoo283pip install -e .284```285286Then use the full path to the package in your MCP configuration.287</details>288289## Configuration290291### Environment Variables292293The server requires the following environment variables:294295| Variable | Required | Description | Example |296|----------|----------|-------------|---------|297| `ODOO_URL` | Yes | Your Odoo instance URL | `https://mycompany.odoo.com` |298| `ODOO_API_KEY` | Yes* | API key for authentication | `0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd` |299| `ODOO_USER` | Yes* | Username (if not using API key) | `admin` |300| `ODOO_PASSWORD` | Yes* | Password (if not using API key) | `admin` |301| `ODOO_DB` | No | Database name (auto-detected if not set) | `mycompany` |302| `ODOO_LOCALE` | No | Language/locale for Odoo responses | `es_ES`, `fr_FR`, `de_DE` |303| `ODOO_YOLO` | No | YOLO mode - bypasses MCP security (⚠️ DEV ONLY) | `off`, `read`, `true` |304305*Either `ODOO_API_KEY` or both `ODOO_USER` and `ODOO_PASSWORD` are required.306307**Notes:**308- If database listing is restricted on your server, you must specify `ODOO_DB`309- API key authentication is recommended for better security310- The server also loads environment variables from a `.env` file in the working directory311312#### Advanced Configuration313314| Variable | Default | Description |315|----------|---------|-------------|316| `ODOO_MCP_DEFAULT_LIMIT` | `10` | Default number of records returned per search |317| `ODOO_MCP_MAX_LIMIT` | `100` | Maximum allowed record limit per request |318| `ODOO_MCP_MAX_SMART_FIELDS` | `15` | Maximum fields returned by smart field selection |319| `ODOO_MCP_LOG_LEVEL` | `INFO` | Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`) |320| `ODOO_MCP_LOG_JSON` | `false` | Enable structured JSON log output |321| `ODOO_MCP_LOG_FILE` | — | Path for rotating log file (10 MB, 5 backups) |322| `ODOO_MCP_TRANSPORT` | `stdio` | Transport type (`stdio`, `streamable-http`) |323| `ODOO_MCP_HOST` | `localhost` | Host to bind for HTTP transport |324| `ODOO_MCP_PORT` | `8000` | Port to bind for HTTP transport |325326### Transport Options327328The server supports multiple transport protocols for different use cases:329330#### 1. **stdio** (Default)331Standard input/output transport - used by desktop AI applications like Claude Desktop.332333```bash334# Default transport - no additional configuration needed335uvx mcp-server-odoo336```337338#### 2. **streamable-http**339Standard HTTP transport for REST API-style access and remote connectivity.340341```bash342# Run with HTTP transport343uvx mcp-server-odoo --transport streamable-http --host 0.0.0.0 --port 8000344345# Or use environment variables346export ODOO_MCP_TRANSPORT=streamable-http347export ODOO_MCP_HOST=0.0.0.0348export ODOO_MCP_PORT=8000349uvx mcp-server-odoo350```351352The HTTP endpoint will be available at: `http://localhost:8000/mcp/`353354> **Note**: SSE (Server-Sent Events) transport has been deprecated in MCP protocol version 2025-03-26. Use streamable-http transport instead for HTTP-based communication. Requires MCP library v1.9.4 or higher for proper session management.355356<details>357<summary>Running streamable-http transport for remote access</summary>358359```json360{361 "mcpServers": {362 "odoo-remote": {363 "command": "uvx",364 "args": ["mcp-server-odoo", "--transport", "streamable-http", "--port", "8080"],365 "env": {366 "ODOO_URL": "https://your-odoo-instance.com",367 "ODOO_API_KEY": "your-api-key-here",368 "ODOO_DB": "your-database-name"369 }370 }371 }372}373```374</details>375376### Setting up Odoo3773781. **Install the MCP module**:379 - Download the [mcp_server](https://apps.odoo.com/apps/modules/18.0/mcp_server) module380 - Install it in your Odoo instance381 - Navigate to Settings > MCP Server3823832. **Enable models for MCP access**:384 - Go to Settings > MCP Server > Enabled Models385 - Add models you want to access (e.g., res.partner, product.product)386 - Configure permissions (read, write, create, delete) per model3873883. **Generate an API key**:389 - Go to Settings > Users & Companies > Users390 - Select your user391 - Under the "API Keys" tab, create a new key392 - Copy the key for your MCP configuration393394### YOLO Mode (Development/Testing Only) ⚠️395396YOLO mode allows the MCP server to connect directly to any standard Odoo instance **without requiring the MCP module**. This mode bypasses all MCP security controls and is intended **ONLY for development, testing, and demos**.397398**🚨 WARNING: Never use YOLO mode in production environments!**399400#### YOLO Mode Levels4014021. **Read-Only Mode** (`ODOO_YOLO=read`):403 - Allows all read operations (search, read, count)404 - Blocks all write operations (create, update, delete)405 - Safe for demos and testing406 - Shows "READ-ONLY" indicators in responses4074082. **Full Access Mode** (`ODOO_YOLO=true`):409 - Allows ALL operations without restrictions410 - Full CRUD access to all models411 - **EXTREMELY DANGEROUS** - use only in isolated environments412 - Shows "FULL ACCESS" warnings in responses413414#### YOLO Mode Configuration415416<details>417<summary>Read-Only YOLO Mode (safer for demos)</summary>418419```json420{421 "mcpServers": {422 "odoo-demo": {423 "command": "uvx",424 "args": ["mcp-server-odoo"],425 "env": {426 "ODOO_URL": "http://localhost:8069",427 "ODOO_USER": "admin",428 "ODOO_PASSWORD": "admin",429 "ODOO_DB": "demo",430 "ODOO_YOLO": "read"431 }432 }433 }434}435```436</details>437438<details>439<summary>Full Access YOLO Mode (⚠️ use with extreme caution)</summary>440441```json442{443 "mcpServers": {444 "odoo-test": {445 "command": "uvx",446 "args": ["mcp-server-odoo"],447 "env": {448 "ODOO_URL": "http://localhost:8069",449 "ODOO_USER": "admin",450 "ODOO_PASSWORD": "admin",451 "ODOO_DB": "test",452 "ODOO_YOLO": "true"453 }454 }455 }456}457```458</details>459460#### When to Use YOLO Mode461462✅ **Appropriate Uses:**463- Local development with test data464- Quick demos with non-sensitive data465- Testing MCP clients before installing the MCP module466- Prototyping in isolated environments467468❌ **Never Use For:**469- Production environments470- Instances with real customer data471- Shared development servers472- Any environment with sensitive information473474#### YOLO Mode Security Notes475476- Connects directly to Odoo's standard XML-RPC endpoints477- Bypasses all MCP access controls and model restrictions478- No rate limiting is applied479- All operations are logged but not restricted480- Model listing shows 200+ models instead of just enabled ones481482## Usage Examples483484Once configured, you can ask Claude:485486**Search & Retrieve:**487- "Show me all customers from Spain"488- "Find products with stock below 10 units"489- "List today's sales orders over $1000"490- "Search for unpaid invoices from last month"491- "Count how many active employees we have"492- "Show me the contact information for Microsoft"493494**Create & Manage:**495- "Create a new customer contact for Acme Corporation"496- "Add a new product called 'Premium Widget' with price $99.99"497- "Create a calendar event for tomorrow at 2 PM"498- "Update the phone number for customer John Doe to +1-555-0123"499- "Change the status of order SO/2024/001 to confirmed"500- "Delete the test contact we created earlier"501502## Available Tools503504### `search_records`505Search for records in any Odoo model with filters.506507```json508{509 "model": "res.partner",510 "domain": [["is_company", "=", true], ["country_id.code", "=", "ES"]],511 "fields": ["name", "email", "phone"],512 "limit": 10513}514```515516**Field Selection Options:**517- Omit `fields` or set to `null`: Returns smart selection of common fields518- Specify field list: Returns only those specific fields519- Use `["__all__"]`: Returns all fields (use with caution)520521### `get_record`522Retrieve a specific record by ID.523524```json525{526 "model": "res.partner",527 "record_id": 42,528 "fields": ["name", "email", "street", "city"]529}530```531532**Field Selection Options:**533- Omit `fields` or set to `null`: Returns smart selection of common fields with metadata534- Specify field list: Returns only those specific fields535- Use `["__all__"]`: Returns all fields without metadata536537### `list_models`538List all models enabled for MCP access.539540```json541{}542```543544### `list_resource_templates`545List available resource URI templates and their patterns.546547```json548{}549```550551### `create_record`552Create a new record in Odoo.553554```json555{556 "model": "res.partner",557 "values": {558 "name": "New Customer",559 "email": "customer@example.com",560 "is_company": true561 }562}563```564565### `update_record`566Update an existing record.567568```json569{570 "model": "res.partner",571 "record_id": 42,572 "values": {573 "phone": "+1234567890",574 "website": "https://example.com"575 }576}577```578579### `delete_record`580Delete a record from Odoo.581582```json583{584 "model": "res.partner",585 "record_id": 42586}587```588589### Smart Field Selection590591When you omit the `fields` parameter (or set it to `null`), the server automatically selects the most relevant fields for each model using a scoring algorithm:592593- **Essential fields** like `id`, `name`, `display_name`, and `active` are always included594- **Business-relevant fields** (state, amount, email, phone, partner, etc.) are prioritized595- **Technical fields** (message threads, activity tracking, website metadata) are excluded596- **Expensive fields** (binary, HTML, large text, computed non-stored) are skipped597598The default limit is 15 fields per request. Responses include metadata showing which fields were returned and how many total fields are available. You can adjust the limit with `ODOO_MCP_MAX_SMART_FIELDS` or bypass it entirely with `fields: ["__all__"]`.599600## Resources601602The server also provides direct access to Odoo data through resource URIs:603604| URI Pattern | Description |605|------------|-------------|606| `odoo://{model}/record/{id}` | Retrieve a specific record by ID |607| `odoo://{model}/search` | Search records with default settings (first 10 records) |608| `odoo://{model}/count` | Count all records in a model |609| `odoo://{model}/fields` | Get field definitions and metadata for a model |610611**Examples:**612- `odoo://res.partner/record/1` — Get partner with ID 1613- `odoo://product.product/search` — List first 10 products614- `odoo://res.partner/count` — Count all partners615- `odoo://product.product/fields` — Show all fields for products616617> **Note:** Resource URIs don't support query parameters (like `?domain=...`). For filtering, pagination, and field selection, use the `search_records` tool instead.618619## How It Works620621```622AI Assistant (Claude, Copilot, etc.)623 ↓ MCP Protocol (stdio or HTTP)624 mcp-server-odoo625 ↓ XML-RPC626 Odoo Instance627```628629The server translates MCP tool calls into Odoo XML-RPC requests. It handles authentication, access control, field selection, data formatting, and error handling — presenting Odoo data in an LLM-friendly hierarchical text format.630631## Security632633- Always use HTTPS in production environments634- Keep your API keys secure and rotate them regularly635- Configure model access carefully - only enable necessary models636- The MCP module respects Odoo's built-in access rights and record rules637- Each API key is linked to a specific user with their permissions638639## Troubleshooting640641<details>642<summary>Connection Issues</summary>643644If you're getting connection errors:6451. Verify your Odoo URL is correct and accessible6462. Check that the MCP module is installed: visit `https://your-odoo.com/mcp/health`6473. Ensure your firewall allows connections to Odoo648</details>649650<details>651<summary>Authentication Errors</summary>652653If authentication fails:6541. Verify your API key is active in Odoo6552. Check that the user has appropriate permissions6563. Try regenerating the API key6574. For username/password auth, ensure 2FA is not enabled658</details>659660<details>661<summary>Model Access Errors</summary>662663If you can't access certain models:6641. Go to Settings > MCP Server > Enabled Models in Odoo6652. Ensure the model is in the list and has appropriate permissions6663. Check that your user has access to that model in Odoo's security settings667</details>668669<details>670<summary>"spawn uvx ENOENT" Error</summary>671672This error means UV is not installed or not in your PATH:673674**Solution 1: Install UV** (see Installation section above)675676**Solution 2: macOS PATH Issue**677Claude Desktop on macOS doesn't inherit your shell's PATH. Try:6781. Quit Claude Desktop completely (Cmd+Q)6792. Open Terminal6803. Launch Claude from Terminal:681 ```bash682 open -a "Claude"683 ```684685**Solution 3: Use Full Path**686Find UV location and use full path:687```bash688which uvx689# Example output: /Users/yourname/.local/bin/uvx690```691692Then update your config:693```json694{695 "command": "/Users/yourname/.local/bin/uvx",696 "args": ["mcp-server-odoo"]697}698```699</details>700701<details>702<summary>Database Configuration Issues</summary>703704If you see "Access Denied" when listing databases:705- This is normal - some Odoo instances restrict database listing for security706- Make sure to specify `ODOO_DB` in your configuration707- The server will use your specified database without validation708709Example configuration:710```json711{712 "env": {713 "ODOO_URL": "https://your-odoo.com",714 "ODOO_API_KEY": "your-key",715 "ODOO_DB": "your-database-name"716 }717}718```719Note: `ODOO_DB` is required if database listing is restricted on your server.720</details>721722<details>723<summary>"SSL: CERTIFICATE_VERIFY_FAILED" Error</summary>724725This error occurs when Python cannot verify SSL certificates, often on macOS or corporate networks.726727**Solution**: Add SSL certificate path to your environment configuration:728729```json730{731 "env": {732 "ODOO_URL": "https://your-odoo.com",733 "ODOO_API_KEY": "your-key",734 "SSL_CERT_FILE": "/etc/ssl/cert.pem"735 }736}737```738739This tells Python where to find the system's SSL certificate bundle for HTTPS connections. The path `/etc/ssl/cert.pem` is the standard location on most systems.740</details>741742<details>743<summary>Debug Mode</summary>744745Enable debug logging for more information:746747```json748{749 "env": {750 "ODOO_URL": "https://your-odoo.com",751 "ODOO_API_KEY": "your-key",752 "ODOO_MCP_LOG_LEVEL": "DEBUG"753 }754}755```756</details>757758## Development759760<details>761<summary>Running from source</summary>762763```bash764# Clone the repository765git clone https://github.com/ivnvxd/mcp-server-odoo.git766cd mcp-server-odoo767768# Install in development mode769pip install -e ".[dev]"770771# Run tests772pytest --cov773774# Run the server775python -m mcp_server_odoo776777# Check version778python -m mcp_server_odoo --version779```780</details>781782<details>783<summary>Testing with MCP Inspector</summary>784785```bash786# Using uvx787npx @modelcontextprotocol/inspector uvx mcp-server-odoo788789# Using local installation790npx @modelcontextprotocol/inspector python -m mcp_server_odoo791```792</details>793794## Testing795796### Transport Tests797798You can test both stdio and streamable-http transports to ensure they're working correctly:799800```bash801# Run comprehensive transport tests802python tests/run_transport_tests.py803```804805This will test:806- **stdio transport**: Basic initialization and communication807- **streamable-http transport**: HTTP endpoint, session management, and tool calls808809### Unit Tests810811For complete testing including unit and integration tests:812813```bash814# Run all tests815uv run pytest --cov816817# Run specific test categories818uv run pytest tests/test_tools.py -v819uv run pytest tests/test_server_foundation.py -v820```821822## License823824This project is licensed under the Mozilla Public License 2.0 (MPL-2.0) - see the [LICENSE](LICENSE) file for details.825826## Contributing827828Contributions are very welcome! Please see the [CONTRIBUTING](CONTRIBUTING.md) guide for details.829830## Support831832Thank you for using this project! If you find it helpful and would like to support my work, kindly consider buying me a coffee. Your support is greatly appreciated!833834<a href="https://www.buymeacoffee.com/ivnvxd" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>835836And do not forget to give the project a star if you like it! :star:
Full transparency — inspect the skill content before installing.