jmceleney/odoo-mcp

Odoo MCP - Model Context Protocol Server for Odoo

This package provides a Model Context Protocol (MCP) server that exposes Odoo functionality to AI assistants like Claude.

Features

• XML-RPC communication with Odoo
• Model discovery and inspection
• Data querying
• MCP server for AI integration

Installation

Using Claude Code (Recommended)

The easiest way to use this MCP server with Claude Code is via uvx:

# Install with environment variables
claude mcp add --transport stdio odoo \
  --env ODOO_URL=https://your-odoo-server.com \
  --env ODOO_DB=your_database_name \
  --env ODOO_USERNAME=your_username \
  --env ODOO_PASSWORD=your_password \
  --env MODEL_EXCLUSION_PREFIXES=ir.,mail.,bus.,base. \
  -- uvx --from git+https://github.com/jmceleney/odoo-mcp odoo-mcp

Using with Cursor IDE

To use this MCP server with Cursor IDE, you need to configure it in your MCP settings file.

Prerequisites:

• Cursor version 0.47.x or above
• Node.js v18.x.x or above

Configuration Steps:

1. Create or edit the MCP configuration file at ~/.cursor/mcp.json (for global settings) or .cursor/mcp.json in your project directory (for project-specific settings)

2. Add the Odoo MCP server configuration:

{
  "mcpServers": {
    "odoo": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/jmceleney/odoo-mcp",
        "odoo-mcp"
      ],
      "env": {
        "ODOO_URL": "https://your-odoo-server.com",
        "ODOO_DB": "your_database_name",
        "ODOO_USERNAME": "your_username",
        "ODOO_PASSWORD": "your_password",
        "MODEL_EXCLUSION_PREFIXES": "ir.,mail.,bus.,base."
      }
    }
  }
}

3. Restart Cursor IDE to load the new configuration

4. The Odoo MCP tools will now be available in Cursor's AI chat. You can ask Cursor to use them, for example: "Please use the Odoo MCP to list all customer models"

Using with .env file:

If you prefer to keep credentials in a .env file, omit the env section from the configuration and ensure your .env file is in your project directory.

Using with VSCode and GitHub Copilot

To use this MCP server with Visual Studio Code and GitHub Copilot, you'll need to configure it as an MCP server.

Prerequisites:

• Visual Studio Code version 1.99 or later (1.102+ recommended for general availability features)
• GitHub Copilot and GitHub Copilot Chat extensions installed and enabled
• Node.js installed for using uvx
• MCP policy enabled by your organisation administrator (if applicable)

Configuration Steps:

Option 1: Using the Command Palette (Recommended)

1. Open VS Code and press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac)
2. Type "MCP: Add Server" and select it
3. Choose whether to add globally or to your workspace
4. When prompted, manually edit the configuration file that opens

Option 2: Manual Configuration

1. Create or edit the MCP configuration file:

   • For workspace-specific: Create .vscode/mcp.json in your project root
   • For global settings: Run MCP: Open User Configuration from the Command Palette

2. Add the Odoo MCP server configuration:

{
  "servers": {
    "odoo": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/jmceleney/odoo-mcp",
        "odoo-mcp"
      ],
      "env": {
        "ODOO_URL": "https://your-odoo-server.com",
        "ODOO_DB": "your_database_name",
        "ODOO_USERNAME": "your_username",
        "ODOO_PASSWORD": "your_password",
        "MODEL_EXCLUSION_PREFIXES": "ir.,mail.,bus.,base."
      }
    }
  }
}

3. Save the file and reload VS Code

Using the MCP Server:

1. Open GitHub Copilot Chat in VS Code (click the Copilot icon in the sidebar)
2. Select Agent Mode from the dropdown menu
3. Click the tools 🔧 icon to view available MCP tools
4. The Odoo MCP tools should now be available
5. You can ask Copilot to use them, for example: "Use the Odoo MCP to search for customers"

Using with .env file:

If you prefer to keep credentials in a .env file in your project directory, you can omit the env section from the configuration, and the MCP server will read from the .env file automatically.

Note: Copilot may automatically suggest MCP tools when relevant, or you can explicitly request them in your prompts. By default, VS Code will ask for permission before activating MCP tools.

Configuration with .env file

Alternatively, create a .env file in your project directory:

# .env
ODOO_URL=https://your-odoo-server.com
ODOO_DB=your_database_name
ODOO_USERNAME=your_username
ODOO_PASSWORD=your_password
MODEL_EXCLUSION_PREFIXES=ir.,mail.,bus.,base.

Then add the MCP server without environment variables (it will read from .env):

claude mcp add --transport stdio odoo -- uvx --from git+https://github.com/jmceleney/odoo-mcp odoo-mcp

Verify Installation

Check that the server is configured:

claude mcp list

You should see odoo in the list of configured MCP servers.

Remove the Server

If you need to remove the server:

claude mcp remove odoo

Local Development Installation

For local development, install the package in editable mode:

# Clone the repository
git clone https://github.com/jmceleney/odoo-mcp.git
cd odoo-mcp

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install in editable mode
pip install -e .

# Run the server
odoo-mcp
# or
python -m odoo_mcp

Testing with uvx

You can test the installation with uvx before adding to Claude Code:

# Test from local directory
cd odoo-mcp
uvx --from . odoo-mcp

# Test from GitHub
uvx --from git+https://github.com/jmceleney/odoo-mcp odoo-mcp

Configuration

The server is configured using environment variables or a .env file:

# .env file example
ODOO_URL=http://localhost:8069
ODOO_DB=your_database_name
ODOO_USERNAME=your_odoo_username
ODOO_PASSWORD=your_secure_password
MODEL_EXCLUSION_PREFIXES=ir.,mail.,bus.,base.

Available Configuration Options

Usage

MCP Tools

The MCP server provides tools for AI assistants including:

• Discovery Tools: list_models, get_model_fields, get_detailed_field_info
• Search Tools: search_records, count_records, search_partners_by_name, search_customers, customer_count
• Module Tools: get_settings, get_module_info, search_products_by_category

See the for the complete list of available tools.

Example Usage with Claude

In Claude, you can interact with Odoo by using these tools:

Please use the Odoo MCP to list all customer models.

Development

Running Tests

pytest

Code Style

# Format code
black .

# Check types
mypy .

# Lint code
flake8 .

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

Documentation

For detailed setup and deployment instructions, see:

• - Comprehensive setup instructions
• - Docker and container deployment

Security

• All operations are read-only by default
• Credentials are handled securely through environment variables
• Use HTTPS for production Odoo connections
• Restrict API user permissions in Odoo

License

MIT License - see file for details.