Odoo MCP Server

A professional Model Context Protocol (MCP) server for seamless Odoo ERP integration. Supports both HTTP and STDIO transports for maximum flexibility.

🚀 Features

🌐 Dual Transport Support

• HTTP Mode: REST API with Express.js for web applications and remote access
• STDIO Mode: Direct stdin/stdout communication for Claude Desktop and local AI assistants

🔧 Complete Odoo Integration

• Authentication: Automatic login with environment variables or manual connect
• CRUD Operations: Full Create, Read, Update, Delete on any Odoo model
• Advanced Search: Complex domain filtering with Odoo's powerful search syntax
• Method Calls: Execute any custom method on Odoo models
• Multi-Protocol: XML-RPC and JSON-RPC support

🏗️ Professional Architecture

• TypeScript: Full type safety and modern ES modules
• MCP Protocol: Compliant with Model Context Protocol 2024-11-05
• Error Handling: Comprehensive error handling and logging
• Modular Design: Clean separation of concerns
• Production Ready: Battle-tested with real Odoo deployments

📦 Installation

NPM (Recommended)

npm install -g @mweinheimer/odoo-mcp-server

From Source

git clone https://github.com/heimerle/odoo-mcp-server.git
cd odoo-mcp-server
npm install
npm run build

⚙️ Configuration

Environment Variables

Create a .env.local file or set these environment variables:

# Odoo Connection (Required)
ODOO_URL=http://your-odoo-instance:8069
ODOO_DB=your_database            # or ODOO_DATABASE
ODOO_USERNAME=your_username
ODOO_PASSWORD=your_password

# Transport Mode
MCP_TRANSPORT=stdio              # 'http' or 'stdio' (default: http)

# Odoo Protocol
ODOO_TRANSPORT=jsonrpc           # 'jsonrpc' or 'xmlrpc' (default: jsonrpc)

# HTTP Mode Settings (only for MCP_TRANSPORT=http)
MCP_HTTP_PORT=3001               # HTTP server port (default: 3001)

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "odoo": {
      "command": "node",
      "args": [
        "/path/to/odoo-mcp-server/dist/stdio-server.js"
      ],
      "env": {
        "ODOO_URL": "http://your-odoo:8069",
        "ODOO_DB": "your_database",
        "ODOO_USERNAME": "your_username",
        "ODOO_PASSWORD": "your_password"
      }
    }
  }
}

Or use the global installation:

{
  "mcpServers": {
    "odoo": {
      "command": "odoo-mcp-server",
      "args": ["--stdio"],
      "env": {
        "ODOO_URL": "http://your-odoo:8069",
        "ODOO_DB": "your_database",
        "ODOO_USERNAME": "your_username",
        "ODOO_PASSWORD": "your_password",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

🚀 Quick Start

HTTP Mode

# Using environment variables
ODOO_URL=http://localhost:8069 \
ODOO_DB=mydb \
ODOO_USERNAME=admin \
ODOO_PASSWORD=admin \
MCP_TRANSPORT=http \
node dist/http-mcp-server.js

# Server starts on http://localhost:3001

STDIO Mode (Claude Desktop)

# Using the dedicated STDIO entry point
ODOO_URL=http://localhost:8069 \
ODOO_DB=mydb \
ODOO_USERNAME=admin \
ODOO_PASSWORD=admin \
node dist/stdio-server.js

🔧 Available Tools

The server provides 13 MCP tools for Odoo interaction:

1. odoo_ping - Test Odoo connection and get server info
2. odoo_connect - Manual login to Odoo (when auto-login is not configured)
3. odoo_search_read - Search and read records with domain filters
4. odoo_create - Create new records in any model
5. odoo_write - Update existing records
6. odoo_unlink - Delete records
7. odoo_call_method - Execute custom methods on models
8. odoo_get_fields - Get field definitions for a model
9. odoo_read - Read specific records by ID
10. odoo_search - Search for record IDs
11. odoo_search_count - Count records matching criteria
12. odoo_name_get - Get display names for records
13. odoo_name_search - Search records by name

📚 Usage Examples

Example 1: Search Customers (HTTP)

curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "odoo_search_read",
      "arguments": {
        "model": "res.partner",
        "domain": [["is_company", "=", true]],
        "fields": ["name", "email", "phone"],
        "limit": 10
      }
    },
    "id": 1
  }'

Example 2: Create Contact (Claude Desktop - STDIO)

Simply ask Claude:

"Create a new contact in Odoo with name 'John Doe', email '[email protected]'"

Claude will use the odoo_create tool automatically.

Example 3: Update Record

curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "odoo_write",
      "arguments": {
        "model": "res.partner",
        "ids": [42],
        "values": {
          "phone": "+1234567890"
        }
      }
    },
    "id": 1
  }'

🧪 Development

Build from Source

git clone https://github.com/heimerle/odoo-mcp-server.git
cd odoo-mcp-server
npm install
npm run build

Development Mode

npm run dev      # Watch mode with auto-recompile
npm run lint     # Run ESLint
npm run test     # Run tests

Project Structure

src/
├── http-mcp-server.ts      # Main HTTP/STDIO server
├── stdio-server.ts         # Dedicated STDIO entry point
├── models/
│   ├── odoo-client.ts     # Odoo API client
│   └── odoo-tools.ts      # MCP tool definitions
├── utils/
│   └── odoo-sanitizer.ts  # Response sanitization
└── types/
    └── index.ts           # TypeScript type definitions

📖 Documentation

• [Quick Start Guide](./QUICK-START.md) - Get started in 5 minutes
• [Examples](./EXAMPLES.md) - Detailed usage examples
• [Transport Modes](./TRANSPORT-MODES.md) - HTTP vs STDIO explained
• [MCP Setup](./MCP-SETUP.md) - Claude Desktop integration
• [Testing Guide](./TESTING-GUIDE.md) - How to test the server
• [Changelog](./CHANGELOG.md) - Version history

🐛 Troubleshooting

STDIO Mode: "Not connected to Odoo"

Make sure you're using the correct environment variable names:

• Use ODOO_DB or ODOO_DATABASE (both work)
• All credentials must be provided for auto-login

HTTP Mode: Port Already in Use

# Check what's using port 3001
lsof -i :3001

# Kill the process
pkill -f "node.*http-mcp-server"

# Or use a different port
MCP_HTTP_PORT=3002 node dist/http-mcp-server.js

Connection Refused

Check that your Odoo instance is accessible:

curl http://your-odoo-instance:8069/web/database/selector

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• GitHub: https://github.com/heimerle/odoo-mcp-server
• NPM: https://www.npmjs.com/package/@mweinheimer/odoo-mcp-server
• Issues: https://github.com/heimerle/odoo-mcp-server/issues

🙏 Acknowledgments

• Built with Model Context Protocol
• Powered by Odoo ERP
• TypeScript and Node.js

Made with ❤️ for the Odoo and AI community