Odoo MCP Framework

v 19.0 Third Party 148

Versions

You bought this module and need support? Click here!

Availability	Odoo Online Odoo.sh On Premise
Lines of code	1805
Technical Name	`mcp_base`
License	LGPL-3
Website	https://github.com/hypsai/odoo_addons/tree/main/mcp_base

Versions

13.0 14.0 15.0 16.0 17.0 18.0 19.0

Odoo MCP Framework

Connect Odoo to AI Agents with One Decorator. Transform your Odoo into a Model Context Protocol (MCP) Server for seamless integration with Claude, ChatGPT, Cursor and other AI agents.

Simple. Elegant. Powerful.

@mcp_tool, AI Integration, MCP Server, Automation

The Simplest Way

@mcp_tool
def search_customers(self, name: str):
    """Search customers by name."""
    # That's it! No config, no schema - just decorate and go

Type hints → JSON Schema Docstring → Descriptions Zero configuration

Why @mcp_tool?

The simplest decorator to expose Odoo methods to AI agents. Just add it and go - no complex setup required.

One-Line Setup

Just @mcp_tool. Your methods are instantly AI-ready.

Zero Config

Automatic JSON schema from type hints and docstrings. No manual work.

Fine-Grained ACL

Per-tool access control on top of standard Odoo ACL — control exactly which AI agents see which tools.

Production Ready

Streamable HTTP, JSON-RPC 2.0, enterprise-grade reliability.

Two Ways to Build Tools

Choose the workflow that fits your team — developer-friendly decorators or admin-friendly UI.

CODE FIRST

Decorate. Ship. Done.

Write Python methods and tag them with @mcp_tool. The framework auto-discovers them on startup:

Python type hints → JSON Schema automatically
Docstrings → parameter descriptions
Respects @api.model and model inheritance
Auto-synced at every server restart

CONFIG FIRST

No Code. Just Configure.

Define tools directly in the Odoo UI — no Python required. Two entry points:

1) Settings → Technical → MCP Framework → Tools (global list)
2) Settings → Technical → Database Structure → Models → MCP Tools tab (scoped to that model)

Note: The Technical menu requires Developer (Debug) Mode — add ?debug=1 to your URL to enable it.

Pick a model and a method from dropdowns
Write a docstring in Google/NumPy/Sphinx style
System auto-generates JSON Schema from your docstring
Editable metadata — description, input schema, active flag

Get Started in 3 Steps

Install Module

Download and install the mcp_base module to your Odoo instance:

Download from Odoo App Store
You'll receive a file named mcp_base-x.x.x.zip
Extract and Place in Addons Directory
Extract the zip file and copy the mcp_base folder to your Odoo addons path, for example:
/opt/odoo/addons/mcp_base (Linux) or C:\Program Files\Odoo 15.0\server\addons\mcp_base (Windows)
Can't find your addons path? Check your Odoo config file:
- Linux: /etc/odoo/odoo.conf (look for addons_path)
- Windows: C:\Program Files\Odoo 15.0\server\odoo.conf
Install via Odoo Interface
Enable Developer Mode by adding ?debug=1 to your URL (e.g., http://localhost:8069/web?debug=1)
Then go to: Apps → Click Update Apps List (top menu) → Search "mcp_base" → Click Install

Decorate Your Methods

Add the @mcp_tool decorator to any Odoo model method you want to expose to AI agents:

from odoo import models
from odoo.addons.mcp_base import mcp_tool

class ResPartner(models.Model):
    _inherit = 'res.partner'

    @mcp_tool
    def search_customers(self, name: str, limit: int = 10):
        """Search customers by name.

        :param name: Customer name to search for
        :param limit: Maximum number of results
        """
        return self.search_read([('name', 'ilike', name)], fields=['name', 'email'], limit=limit)

Connect AI Clients

Configure your AI client to connect to the MCP server endpoint and set up one of the authentication methods below:

Your MCP Endpoint:

http://your-odoo-server:8069/mcp

Authentication (choose one):

Plain text headers — X-User: your-loginname and X-Password: your-password
HTTP Basic Auth — Authorization: Basic <base64-credentials>
API Key — If you have auth_api_key module installed, add Api-Key: your-api-key-here

Popular AI Clients:

ChatWise

Settings → MCP → Add Server

Cursor

Settings → MCP → Add Server

Claude Desktop

Edit config.json

You're All Set!

Your Odoo methods are now accessible to AI agents. Start asking natural language questions about your data!

Access Control (ACL)

Tools are inaccessible without proper ACL configuration. Set up access rights before connecting AI clients.

Menu Entry

Settings → Technical → MCP Framework → Access Rights

Important: The Technical menu is only visible when Developer (Debug) Mode is enabled. To activate it, add ?debug=1 to your URL (e.g., http://localhost:8069/web?debug=1), or click the bug icon in the header bar.

From the Access Rights menu, you can configure per-tool access control rules that determine which Odoo groups and users are allowed to invoke specific MCP tools. This works alongside standard Odoo ACL — a user must have both the Odoo model access and the MCP tool access to use a tool.

Security & Authentication

Three authentication options — plain text, Basic Auth, or API keys.

Default Authentication (Plain Text Headers)

The simplest method — just set two headers with your Odoo username and password. No base64 encoding required.

X-User: your-loginname
X-Password: your-password

Claude Desktop example:

{
  "mcpServers": {
    "odoo": {
      "url": "http://localhost:8069/mcp",
      "transport": "streamable-http",
      "headers": {
        "X-User": "your-loginname",
        "X-Password": "your-password"
      }
    }
  }
}

HTTP Basic Auth (Alternative)

Standard Authorization: Basic <base64-credentials> is also supported as a fallback:

{
  "mcpServers": {
    "odoo": {
      "url": "http://localhost:8069/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Basic <base64(username:password)>"
      }
    }
  }
}

API Key Authentication (Recommended for Production)

For enhanced security, install the auth_api_key module to use API keys instead of passwords:

Install auth_api_key

Download from Odoo App Store.

Create an API Key

Settings Technical API Keys Create
Set name and choose target user
Copy the generated API key

Note: The Technical menu requires Developer (Debug) Mode — add ?debug=1 to your URL to enable it.

Configure Your Client

Add header: Api-Key: your-api-key-here

{
  "mcpServers": {
    "odoo": {
      "url": "http://localhost:8069/mcp",
      "transport": "streamable-http",
      "headers": {
        "Api-Key": "your-api-key-here"
      }
    }
  }
}

Note: When you provide an Api-Key header (with auth_api_key installed), it takes priority. Without it, plain text or Basic Auth credentials are accepted as fallback.

Ready to Make Your Odoo AI-Ready?

Install Odoo MCP Framework and expose your first method with @mcp_tool in under 2 minutes.

Star on GitHub

Please log in to comment on this module

The author can leave a single reply to each comment.
This section is meant to ask simple questions or leave a rating. Every report of a problem experienced while using the module should be addressed to the author directly (refer to the following point).
If you want to start a discussion with the author, please use the developer contact information. They can usually be found in the description.