MCP Server for Odoo

1. What Is MCP Server for Odoo?

MCP Server for Odoo turns your Odoo instance into a secure data source that any AI assistant — Claude, ChatGPT, Gemini, or a custom agent — can query and act on through a standard protocol called the Model Context Protocol (MCP).

Instead of giving an AI tool direct database access or writing custom integrations, you install one module. From that point, your AI assistants can:

• Search and read any Odoo record they are permitted to access
• Create, update, and delete records on your behalf
• Generate analytics, pivot tables, time-series charts, and funnels from live data
• Build and publish public data pages with live Odoo data
• Generate and install new Odoo modules through conversation
• Trigger AI analysis on individual records and receive results in the chatter

Everything happens through a single secure endpoint (/mcp) with full audit logging of every request.

2. Module Overview

The MCP Server PRO package consists of the following modules. Each is installed separately and serves a distinct purpose.

2.1 MCP Server PRO mcp_server_odoo

The core module. Required for everything else.

• The /mcp JSON-RPC endpoint
• API key management with SHA-256 hashing
• Per-key model, field, and domain-level access control
• 30+ MCP tools covering read, write, analytics, batch operations, and async jobs
• Full audit logging, rate limiting, and Redis integration
• Settings page under MCP → Settings

2.2 OAuth 2.1 mcp_server_odoo_oauth

Adds OAuth 2.1 with PKCE so AI clients like Claude.ai and ChatGPT can connect through a proper browser-based login flow rather than a manually configured API key.

• OAuth authorization, token, and revocation endpoints
• Dynamic Client Registration for automatic AI client onboarding
• Shared client creation wizard for team deployments
• Token rotation with 1-hour access tokens and 30-day rotating refresh tokens
• Discovery endpoints (.well-known/oauth-protected-resource, .well-known/oauth-authorization-server)
• PKCE enforcement — no implicit grants

2.3 Portal Pages mcp_server_odoo_portal

Lets AI assistants create public-facing web pages that display live Odoo data — no coding required.

• Public pages at /mcp-page/{your-slug}
• Nine section types: KPI Cards, Charts, Tables, Progress Bars, Comparisons, Timelines, Metric Grids, Heatmaps, and Rich Text
• Per-page custom theme (brand colour, logo, font)
• URL filter parameters for dynamic filtering
• MCP tools: create_portal_page, update_portal_page, list_portal_pages, delete_portal_page

2.4 KSRO AI Engine ksro_ai_engine Add-on

Embeds AI directly inside Odoo server actions. Configure a "Generative AI" action on any Odoo model — when triggered, it reads the record, sends it to your chosen AI provider, and writes the response back to the chatter, a field, or as a new activity.

• Support for OpenAI, Anthropic Claude, Google Gemini, and Mistral
• System prompt + per-record Jinja2 prompt templates
• Real-time browser notifications when AI completes
• Full audit log per AI call and prompt preview wizard

2.5 KSRO Web Notify ksro_web_notify Add-on

Real-time browser notifications via Odoo Bus. Used by KSRO AI Engine to push "Agent finished" toasts to the user's browser without a page reload.

3. Requirements

4. Installation

4.1 Odoo.sh (Recommended)

Odoo.sh links your Odoo instance to a GitHub repository. Custom modules are installed by adding them to that repository and deploying.

Step 1 — Get the module files from KSRO Labs after purchasing. Clone or download:

• mcp_server_odoo
• mcp_server_odoo_oauth
• mcp_server_odoo_portal

Step 2 — Copy the module folders into the root of your Odoo.sh GitHub repository:

your-odoo-repo/
├── mcp_server_odoo/
├── mcp_server_odoo_oauth/
├── mcp_server_odoo_portal/
└── (your other custom modules)

Step 3 — Commit and push:

git add mcp_server_odoo mcp_server_odoo_oauth mcp_server_odoo_portal
git commit -m "Add MCP Server PRO modules"
git push origin main

Odoo.sh will automatically detect the new modules and rebuild the instance.

Step 4 — Install in Odoo:

1. Go to Apps in Odoo
2. Click Update Apps List (requires Developer Mode)
3. Search for "MCP Server"
4. Install MCP Server PRO first
5. Then install MCP Server OAuth 2.1
6. Then install Portal Pages (if purchased)

4.2 Self-Hosted / On-Premise

Step 1 — Copy the module folders to your Odoo custom addons directory:

cp -r mcp_server_odoo /opt/odoo/custom-addons/
cp -r mcp_server_odoo_oauth /opt/odoo/custom-addons/
cp -r mcp_server_odoo_portal /opt/odoo/custom-addons/

Confirm the addons path is registered in your odoo.conf:

[options]
addons_path = /opt/odoo/addons,/opt/odoo/custom-addons

Step 2 — Restart Odoo:

sudo systemctl restart odoo

Step 3 — Install in Odoo using the same steps as Section 4.1 Step 4.

4.3 Installing KSRO AI Engine (Add-on)

Install the required Python dependencies:

pip install openai anthropic google-genai mistralai markdown-it-py

Then add the module folders to your repository/addons path and install in Odoo in this order:

1. ksro_web_notify — install first
2. ksro_ai_engine — install second (depends on ksro_web_notify)

5. Initial Configuration

5.1 Enable Developer Mode

Several configuration steps require Developer Mode to be active.

Go to Settings → General Settings → scroll to the bottom → Activate the developer mode

Or navigate directly to:

https://your-odoo.com/web?debug=1

5.2 Verify the MCP Endpoint

Once the module is installed, your MCP endpoint is live at:

https://your-odoo.com/mcp

You can verify it is active by opening this URL in a browser. You will see an empty response or a CORS header — this is correct. The endpoint only responds to POST requests with a valid JSON-RPC payload. The endpoint URL is also shown in Odoo → Settings → MCP Server → MCP Endpoint URL.

5.3 Basic Settings

Go to Settings → MCP Server (scroll to the MCP Server section).

6. API Keys — The Foundation of Access Control

API keys are the credentials that allow AI tools to authenticate with your MCP server. Each key represents a distinct access identity with its own permission scope.

6.1 Creating an API Key

1. Go to MCP → API Keys
2. Click New
3. Fill in: Name (e.g., "Sales Team — Claude Desktop"), User (the Odoo user this key acts as), Active (keep checked)
4. Click Save
5. The system generates a Bearer token and shows it once. Copy it immediately — it cannot be retrieved again.

6.2 Token Versioning

Each key can have multiple active token versions simultaneously. This allows seamless rotation:

1. Generate a new token version
2. Update your AI client configuration with the new token
3. Revoke the old token version

6.3 Token Rotation

Token rotation runs automatically on a schedule. When a token is rotated, the current token continues working for a grace period, a new token is generated, and the old token is revoked after the grace period. You can also rotate tokens manually from the API Key form view.

6.4 How to Use the API Key

Provide the key as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_TOKEN_HERE

In Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "odoo": {
      "url": "https://your-odoo.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

7. Key Model Access — Permissions Per Key

7.1 Adding Model Access to a Key

1. Go to MCP → Key Model Access
2. Click New
3. Select the API Key
4. Select the Model (e.g., sale.order, crm.lead, res.partner)
5. Check which operations to allow: Read, Create, Write, Delete
6. Optionally configure Domain Filter and Allowed Fields
7. Click Save

Repeat for each model the key should access.

7.2 Domain Filter — Restricting Which Records Are Visible

For any model in a key's scope, you can restrict which records are visible using an Odoo domain expression.

# Only see opportunities in a specific team
[["team_id.name", "=", "Europe Sales"]]

# Only see active customers
[["customer_rank", ">", 0], ["active", "=", true]]

The domain is enforced at the database level — the AI cannot request records outside it regardless of how the query is phrased.

7.3 Allowed Fields — Restricting Which Fields Are Returned

You can define an allowlist of field names. Fields not on the list are stripped from every response, including responses to explicit requests. Leave the list empty to permit all fields the associated Odoo user can read.

7.4 Example Permission Scenarios

8. Connecting AI Tools

8.1 Claude Desktop

1. Install Claude Desktop from anthropic.com
2. Open the configuration file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
3. Add your MCP server:

   {
     "mcpServers": {
       "odoo": {
         "url": "https://your-odoo.com/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_API_KEY_TOKEN"
         }
       }
     }
   }

4. Save the file and restart Claude Desktop
5. You should see "odoo" appear in the tools panel

8.2 Claude.ai (Browser — OAuth)

Claude.ai supports connecting to MCP servers through the browser interface using OAuth. This requires the OAuth module to be installed. See Section 9 — OAuth Setup.

8.3 ChatGPT (Custom Connector)

1. Go to ChatGPT → Settings → Connectors → Add custom connector
2. Enter your MCP endpoint URL: https://your-odoo.com/mcp
3. In Advanced Settings, enter your Client ID and Client Secret from a Shared OAuth Client (see Section 9.3)
4. Authorise the connection — you will be redirected to your Odoo login page

8.4 Custom Agents and Automation Tools

Any tool that supports the MCP 1.0 protocol can connect. Provide:

Endpoint URL: https://your-odoo.com/mcp
Authentication: Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
Method: POST

# Initialise with:
{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}

9. OAuth 2.1 Setup (Claude.ai & ChatGPT)

OAuth allows users to log in with their own Odoo credentials rather than sharing API keys. It is the recommended approach for Claude.ai and ChatGPT connectors.

9.1 How OAuth Works

1. You (or the AI client) register an OAuth application with your Odoo instance
2. When a user connects, they are redirected to your Odoo login page
3. They log in with their Odoo credentials and approve access
4. The AI client receives a Bearer token valid for 1 hour
5. After 1 hour, the client automatically refreshes using a refresh token (valid 30 days)
6. After 30 days, the user logs in again

Each user who connects gets their own token with their own Odoo permissions — no shared credentials.

9.2 Auto-Discovery

Clients that support OAuth 2.1 auto-discovery (including Claude.ai and ChatGPT) do not need manual configuration. They discover everything from your endpoint:

• Your endpoint returns a WWW-Authenticate header pointing to the discovery URL
• The client fetches https://your-odoo.com/.well-known/oauth-protected-resource
• From there it discovers the authorization and token endpoints automatically
• The user is prompted to log in — no further admin configuration needed

9.3 Creating a Shared Client (For Teams)

1. Go to MCP → OAuth Clients
2. Click the gear icon (⚙️) → Create Shared Client
3. Enter a name (e.g., "Team ChatGPT Connector")
4. Review the pre-filled redirect URIs (covers Claude.ai, ChatGPT, and localhost)
5. Click Generate Credentials
6. Copy the Client ID and Client Secret immediately — the secret is shown only once
7. Share these two values with team members to paste into their AI client Advanced Settings

9.4 Approving OAuth Clients

When a new OAuth client registers automatically (Dynamic Client Registration):

1. Go to MCP → OAuth Clients
2. Find the new client and toggle Approved
3. Optionally toggle Whitelisted for trusted clients to skip manual approval on future registrations

Common redirect URIs to include for known AI clients:

https://claude.ai/api/mcp/auth_callback
https://chatgpt.com/connector_platform_oauth_redirect

10. Portal Pages

Portal pages let you create public-facing web pages that display live Odoo data — without writing any HTML or code. AI assistants can create and update these pages through conversation.

10.1 Section Types

10.2 Creating a Page via Conversation

Tell your AI assistant:

The page is immediately live at:

https://your-odoo.com/mcp-page/sales-dashboard

10.3 URL Filters

# Filter by date range
https://your-odoo.com/mcp-page/sales-dashboard?date_from=2026-01-01&date_to=2026-03-31

# Filter by field value
https://your-odoo.com/mcp-page/sales-dashboard?team_id=5

10.4 Custom Theming

{
  "primary": "#1a1a2e",
  "logo_url": "https://your-company.com/logo.png",
  "font": "Inter"
}

11. Module Builder

The Module Builder lets you describe an Odoo module in plain language and have the AI generate a fully installable, ready-to-use Odoo module.

11.1 The Workflow

Step 1 — Generate the specification

The AI calls generate_module_spec and creates a structured specification.

Step 2 — Build the module

The AI calls build_module_zip. The system validates the specification and generates Python model files, list/form/search view XML, security groups,ir.model.access.csv, app menu and window actions, and a README — packaged into a ZIP file.

Step 3 — Install

The AI calls install_module_zip to upload and activate the module directly in your Odoo instance. The new app is live in the same session.

11.2 Supported Field Types

Char, Integer, Float, Boolean, Date, Datetime, Text, Html, Binary, Selection, Many2one, One2many, Many2many

11.3 What Every Generated Module Includes

• active field (Boolean) — enables archiving records
• company_id field (Many2one → res.company) — multi-company support
• Standard Odoo module structure compatible with Odoo 18
• All views, security, menus, and actions — ready to use with zero extra configuration

12. KSRO AI Engine — Triggering AI From Odoo Records

12.1 Setting Up an AI Provider

1. Go to KSRO AI → Providers
2. Click the provider you want (OpenAI, Anthropic, Google, or Mistral)
3. Paste your API key and click Save
4. Click Test Connection

12.2 Creating an AI Server Action

1. Go to Settings → Technical → Actions → Server Actions → New
2. Set the Model (e.g., crm.lead) and Action Type to Generative AI (KSRO)
3. Choose your AI Model
4. Write a System Prompt (permanent AI persona)
5. Write a Prompt Template using Jinja2 variables:

   Opportunity: {{ record.name }}
   Customer: {{ record.partner_id.name }}
   Expected revenue: {{ record.expected_revenue }}
   Stage: {{ record.stage_id.name }}

6. Set Output Destination: Post to Chatter, Write to Field, or Create Activity

12.3 What the User Experiences

1. User opens a record and clicks the button
2. Browser notification fires: "Agent is working on it…"
3. AI runs in a background thread (20–40 seconds)
4. Another notification: "Agent finished."
5. User opens the chatter — the AI analysis is posted as a permanent private note

No page reload. No waiting with a spinner.

13. Audit Logs & Monitoring

13.1 What Is Logged

Every request to the /mcp endpoint is recorded in mcp.audit.log. Each entry contains:

13.2 Accessing Audit Logs

Go to MCP → Audit Logs. Use the search bar and filters to find requests by key, failed status, write operations, model, or IP address.

13.3 Log Retention

Default retention: 90 days. To keep logs indefinitely, set Settings → MCP Server → Audit Retention → 0. To export logs, use Odoo's standard export functionality from the Audit Logs list view.

14. Security Best Practices

14.1 Principle of Least Privilege

Never give a key more access than it absolutely needs.

• A key used only for reading sales reports should have Read-only access to CRM and Sales models only
• A key used for a specific automation should have Write access only to the specific model it writes to
• No key should have Delete access unless deletion is an explicit, tested, required operation

14.2 One Key Per AI Client / Use Case

Create a separate key for each AI tool and each distinct use case. This gives you a clean audit trail per client and the ability to revoke one key without affecting others.

14.3 Models to Never Grant Write Access To

• res.users — user management
• ir.config_parameter — system parameters
• account.move (posted invoices) — accounting integrity
• ir.module.module — module installation
• Any model containing salary, payroll, or medical data

14.4 Use OAuth for User-Facing Connections

For connections where a specific Odoo user is sitting at a keyboard (Claude.ai browser, ChatGPT), use OAuth rather than a shared API key. Use API keys for automated agents and programmatic access where a human user is not involved.

14.5 Enable Rate Limiting

Set a global rate limit in Settings to prevent runaway agents from hammering your Odoo instance. 60 requests per minute is a reasonable starting point for most deployments.

14.6 Rotate Tokens Regularly

Set a token rotation schedule appropriate for your security policy. Monthly rotation is a reasonable default. For high-security environments, weekly or shorter.

15. Multi-User & Team Setup

15.1 Recommended Structure for Teams

Step 1 — Create a dedicated Odoo user per department (optional but recommended):

• [email protected] — Odoo user in the Sales group
• [email protected] — Odoo user in the Finance group
• [email protected] — Odoo user in the HR group

Step 2 — Create one API key per department, assigned to its corresponding departmental user and scoped to only the models that department needs.

Step 3 — Distribute the tokens. Do not share the same token across departments.

Step 4 — Use OAuth for individual user connections (Claude.ai, ChatGPT) so each person authenticates individually.

15.2 Shared OAuth Client for Teams

1. Go to MCP → OAuth Clients → gear icon → Create Shared Client
2. Name it (e.g., "Company ChatGPT Connector")
3. Click Generate Credentials
4. Copy the Client ID and Client Secret
5. Distribute to team members via a secure channel (password manager, IT department, etc.)

16. Performance & Rate Limiting

16.1 Single-Worker Deployments

For most Odoo instances running one worker process, the default in-memory rate limiting is sufficient. Set your global rate limit in Settings and it will be enforced correctly.

16.2 Multi-Worker Deployments (Redis)

If your Odoo instance runs multiple worker processes, in-memory rate limiting applies per-worker rather than globally. To enforce rate limits correctly across all workers:

1. Install and start Redis on your server
2. Go to Settings → MCP Server → Enable Redis for Rate Limiting & Caching
3. Set the Redis URL (default: redis://localhost:6379/0)

16.3 Expected Performance

17. Troubleshooting

https://claude.ai/api/mcp/auth_callback
https://chatgpt.com/connector_platform_oauth_redirect

18. Frequently Asked Questions