# MCP Odoo Bridge Server
[](https://modelcontextprotocol.io/)
[](https://www.odoo.com/)
[](https://python.org/)
[](LICENSE)
> **Licensed under the Apache License, Version 2.0** - See [LICENSE](LICENSE) for details.
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI assistants like **Claude** to interact with **Odoo** data using natural language.
## 🎯 What is MCP?
The [Model Context Protocol](https://modelcontextprotocol.io/introduction) is an open standard by Anthropic that enables AI assistants to securely connect to external data sources. This server acts as a bridge between Claude (or other MCP clients) and your Odoo instance.
**Learn more:** [MCP Documentation](https://modelcontextprotocol.io/docs)
---
## ✨ Features
| Feature | Description |
|---------|-------------|
| 🔍 **Search Records** | Find records using natural language or Odoo domain syntax |
| 📖 **Read Records** | Get detailed record information by ID |
| 📊 **Count Records** | Get counts matching criteria |
| ➕ **Create Records** | Create new records (with permission) |
| ✏️ **Update Records** | Modify existing records (with permission) |
| 🗑️ **Delete Records** | Remove records (with permission) |
| 📋 **List Models** | Discover available models |
| 🔧 **Get Fields** | Understand model structure |
| ⚡ **Execute Methods** | Run custom methods (if enabled) |
| 🔐 **API Key Auth** | Secure authentication via API keys |
| 📝 **Audit Logging** | All operations logged for compliance |
---
## 📋 Prerequisites
1. **Odoo** instance (17.0, 18.0, or 19.0 recommended)
2. **Python 3.10+** installed
3. **AD Odoo MCP Bridge** module installed in Odoo (see [Odoo Module](#odoo-module))
---
## 🚀 Installation
### 1. Clone the Repository
```bash
git clone https://github.com/yourusername/ad-mcp-bridge-server.git
cd ad-mcp-bridge-server
```
### 2. Install Dependencies
```bash
pip install -e .
```
Or with uv:
```bash
uv pip install -e .
```
### 3. Install the Odoo Module
Install the `ad_odoo_mcp_bridge` module in your Odoo instance:
1. Add the module folder to your Odoo addons path
2. Go to **Apps** → Install **"AD Odoo MCP Bridge"**
---
## ⚙️ Configuration
### Environment Variables
The server requires the following environment variables:
| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `ODOO_URL` | Yes | Your Odoo instance URL | `https://mycompany.odoo.com` |
| `ODOO_API_KEY` | Yes* | API key for authentication | `0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd` |
| `ODOO_USER` | Yes* | Username (if not using API key) | `admin` |
| `ODOO_PASSWORD` | Yes* | Password (if not using API key) | `admin` |
| `ODOO_DB` | No | Database name (auto-detected if not set) | `mycompany` |
| `ODOO_MAX_RECORDS` | No | Default max records per query (default: `100`) | `200` |
| `ODOO_TIMEOUT` | No | Request timeout in seconds (default: `30`) | `60` |
| `ODOO_YOLO` | No | YOLO mode - bypasses MCP security (⚠️ DEV ONLY) | `off`, `read`, `true` |
> **\* Authentication**: You must provide either `ODOO_API_KEY` **or** both `ODOO_USER` and `ODOO_PASSWORD`.
#### MCP Transport Options
| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `MCP_TRANSPORT` | No | Transport type: `stdio` or `streamable-http` (default: `stdio`) | `streamable-http` |
| `MCP_HOST` | No | Host for HTTP transport (default: `localhost`) | `0.0.0.0` |
| `MCP_PORT` | No | Port for HTTP transport (default: `8000`) | `8080` |
#### YOLO Mode Values
| Value | Description |
|-------|-------------|
| `off` | All operations require explicit MCP Bridge permissions (default) |
| `read` | Allows read-only operations on all models without configuration |
| `true` | **⚠️ DANGEROUS** - Allows all operations including write/delete without restrictions |
> **⚠️ Warning**: YOLO mode bypasses security checks and should **NEVER** be used in production. It's intended only for local development and testing.
### Create a `.env` File (Optional)
```env
ODOO_URL=https://mycompany.odoo.com
ODOO_DB=mycompany
ODOO_API_KEY=your-api-key-here
```
---
## 🔌 Usage with Claude Desktop
### Step 1: Generate API Key in Odoo
1. Go to **MCP Bridge → Configuration → API Keys**
2. Click **Create** → Select user → **Generate Key**
3. Copy the key (shown only once!)
### Step 2: Configure Claude Desktop
Edit `claude_desktop_config.json`:
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"odoo": {
"command": "python",
"args": ["-m", "ad_mcp_bridge_server"],
"cwd": "/path/to/ad-mcp-bridge-server/src",
"env": {
"ODOO_URL": "http://localhost:8069",
"ODOO_DB": "your_database",
"ODOO_API_KEY": "your-api-key"
}
}
}
}
```
> **Windows Note:** Use the full Python path if needed:
> ```json
> "command": "C:\\path\\to\\venv\\Scripts\\python.exe"
> ```
### Step 3: Restart Claude Desktop
Close and reopen Claude Desktop. You should see the 🔧 Tools icon.
### Step 4: Start Chatting!
Try these prompts:
- *"Show me all customers from the United States"*
- *"What's the status of order SO/2024/0153?"*
- *"Create a new lead for ABC Company"*
- *"How many unpaid invoices do we have?"*
---
## 🔌 Usage with VS Code
Create `.vscode/mcp.json` in your workspace:
```json
{
"servers": {
"odoo": {
"command": "python",
"args": ["-m", "ad_mcp_bridge_server"],
"cwd": "/path/to/ad-mcp-bridge-server/src",
"env": {
"ODOO_URL": "http://localhost:8069",
"ODOO_DB": "your_database",
"ODOO_API_KEY": "your-api-key"
}
}
}
}
```
---
## 🧪 Testing with MCP Inspector
Use the official MCP debugging tool:
```bash
npx @modelcontextprotocol/inspector python -m ad_mcp_bridge_server
```
This opens a web UI to test all tools interactively.
---
## 🏗️ Odoo Module
This MCP server requires the **AD Odoo MCP Bridge** module installed in Odoo.
### Compatibility
| Odoo Version | Status |
|--------------|--------|
| 19.0 | ✅ Fully Supported |
| 18.0 | ✅ Supported |
| 17.0 | ✅ Supported |
| 16.0 | ✅ Supported |
### Module Features
- **Model Configuration**: Choose which models AI can access
- **Permission Control**: Set read/create/update/delete per model
- **API Key Management**: Generate and manage API keys
- **Audit Logging**: Track all AI operations
- **Rate Limiting**: Control request frequency
- **YOLO Mode**: Quick access mode for development
### Module Installation
1. Copy `ad_odoo_mcp_bridge` folder to your Odoo addons path
2. Restart Odoo
3. Go to **Apps** → Remove "Apps" filter → Search "MCP" → Install
---
## 🔐 Security
- **API Key Authentication**: All requests require a valid API key
- **Permission Inheritance**: AI inherits Odoo user's permissions
- **Audit Trail**: All operations logged with IP, timestamp, and details
- **Rate Limiting**: Configurable per-key request limits
- **Field Exclusions**: Sensitive fields can be blocked
---
## 📚 API Endpoints (Odoo Module)
The Odoo module exposes these JSON-RPC endpoints:
| Endpoint | Description |
|----------|-------------|
| `GET /mcp/health` | Health check |
| `POST /mcp/info` | Server information |
| `POST /mcp/models` | List enabled models |
| `POST /mcp/fields` | Get model fields |
| `POST /mcp/search` | Search records |
| `POST /mcp/read` | Read record by ID |
| `POST /mcp/count` | Count records |
| `POST /mcp/create` | Create record |
| `POST /mcp/write` | Update record |
| `POST /mcp/unlink` | Delete record |
| `POST /mcp/execute` | Execute method |
---
## 🛠️ Development
### Run Locally
```bash
cd src
export ODOO_URL=http://localhost:8069
export ODOO_DB=mydb
export ODOO_API_KEY=your-key
python -m ad_mcp_bridge_server
```
### Project Structure
```
ad-mcp-bridge-server/
├── src/
│ └── ad_mcp_bridge_server/
│ ├── __init__.py
│ ├── __main__.py # Entry point
│ ├── config.py # Pydantic settings
│ ├── odoo_client.py # Odoo HTTP client
│ └── server.py # MCP server & tools
├── pyproject.toml
├── README.md
└── .env.example
```
---
## 📖 MCP Resources
- [Model Context Protocol Specification](https://modelcontextprotocol.io/specification)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [Claude Desktop MCP Setup](https://modelcontextprotocol.io/quickstart/user)
- [Building MCP Servers](https://modelcontextprotocol.io/quickstart/server)
---
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
---
## ☕ Support
Thank 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!
<a href="https://ko-fi.com/aadilakbar" target="_blank">
<img src="https://ko-fi.com/img/githubbutton_sm.svg" alt="Buy Me a Coffee at ko-fi.com" />
</a>
And don't forget to give the project a ⭐ star if you like it!
---
## 📄 License
This project is licensed under the **Apache License 2.0** - see the [LICENSE](LICENSE) file for details.
---
## 🙏 Acknowledgments
- [Anthropic](https://anthropic.com/) for Claude and MCP
- [Odoo](https://odoo.com/) for the amazing ERP platform
- [FastMCP](https://github.com/jlowin/fastmcp) for the Python MCP framework
---
## 📝 About
A Model Context Protocol (MCP) server that enables AI assistants to securely interact with Odoo ERP systems through standardized resources and tools for data retrieval and manipulation.
**Made with ❤️ for the Odoo and AI community**
