<div align="center">

Odoo Claude MCP

Production-grade Model Context Protocol (MCP) server suite for Odoo ERP

Odoo MCP server for Claude Code and Claude.ai — turn any self-hosted Odoo instance (15 → 19) into an AI assistant via the Model Context Protocol. 197+ tools, multi-tenant, Bulgaria localization (НАП, ДДС, ЕИК) included.

Connect Claude, Claude Code, and any MCP-compatible client to Odoo, GitHub, filesystem, Portainer, Teams, and more — through a unified, authenticated gateway.

Quick Start · Why this vs alternatives? · Use Cases · Architecture · MCP Servers · Companion Modules · Deployment

🇧🇬 Български README

</div>

---

<div align="center">

See Claude editing a live Odoo sale order — real CRUD, real auto-recalculation

▶ Watch the full 4-minute demo: Running Odoo 18 Entirely Through AI — Claude Code + MCP Server

</div>

---

🎯 What is odoo-claude-mcp?

odoo-claude-mcp is a self-hosted MCP server suite that turns any Odoo instance into a first-class citizen in the Claude ecosystem. It exposes Odoo data and operations through the Model Context Protocol, while bundling complementary MCP servers for everything an Odoo developer, consultant, or business user needs — GitHub, OCA modules, Kubernetes/Portainer, Microsoft Teams, and a full Claude Code terminal running in the browser.

Unlike single-purpose MCP wrappers, this stack is built for real production use:

• 🔐 Unified authentication across all MCP endpoints via token-based auth
• 🏢 Multi-connection, multi-tenant — one stack serves dozens of Odoo databases
• 🌐 Claude.ai connector ready — public HTTPS endpoint with token auth
• ☸️ K3s / Kubernetes native with Kustomize overlays for dev and prod
• 🐳 Docker Compose for solo developers and small teams
• 🖥️ Web-based terminal — xterm.js + tmux + Claude Code in the browser
• 📦 Odoo module deployment via direct RPC (no filesystem access needed)
• 🔍 Qdrant vector store integration for semantic search across records
• 🤖 Ollama integration for local LLMs and privacy-first deployments

---

🚀 Quick Start

Option 1: Docker Compose (local dev)

git clone https://github.com/rosenvladimirov/odoo-claude-mcp.git
cd odoo-claude-mcp

# Configure
cp .env.example .env
nano .env                    # set ODOO_URL, DB, credentials, tokens

# Create the shared Cloudflare tunnel network (one-time per host)
docker network create cloudflare-net

# Start the stack
docker compose up -d

# Verify
docker compose ps
curl http://localhost:8084/health

No Cloudflare tunnel? If you're deploying locally without a Cloudflare sidecar, use the override file instead of creating the external network:

docker compose -f docker-compose.yml -f docker-compose.local.yml up -d

This turns cloudflare-net into a regular Docker bridge network created on demand.

Optional services (Portainer / Teams). The default docker compose up -d starts only the core stack (Odoo RPC, Filesystem, OCA, EE, GitHub, Qdrant, Ollama, Claude Terminal). To also enable the Portainer MCP or Microsoft Teams MCP, opt in with a Compose profile:

docker compose --profile portainer up -d        # core + Portainer
docker compose --profile teams     up -d        # core + Teams
docker compose --profile full      up -d        # everything

Each optional service has its own required env vars (see .env.example). Without them the service container would crash-loop, so they're skipped by default.

First-run troubleshooting. If docker compose ps shows mcp-odoo-rpc in Restarting state, it means the values in .env (ODOO_URL, ODOO_DB, ODOO_USERNAME, ODOO_API_KEY/ODOO_PASSWORD) don't point to a reachable Odoo instance. Edit .env to match a real Odoo and re-run docker compose up -d. The healthcheck curl http://localhost:8084/health will succeed only after mcp-odoo-rpc is Up.

Option 2: Quick installer script

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/rosenvladimirov/odoo-claude-mcp/2.0/install.sh | bash

Windows (PowerShell as Administrator):

iwr -useb https://raw.githubusercontent.com/rosenvladimirov/odoo-claude-mcp/2.0/install.ps1 | iex

Option 3: Connect to Claude Code

After the stack is running, add it to Claude Code:

claude mcp add odoo-mcp \
  --url https://your-domain.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Or use the included .mcp.json:

cp claude-terminal/.mcp.json ~/.config/claude-code/mcp.json

---

⚖️ Why this vs alternatives?

| Capability | Raw XML-RPC | Single-purpose MCP-Odoo wrappers | odoo-claude-mcp | |---|---|---|---| | Auth | Per-call password | Single shared token | ✅ Bearer + per-user profiles + OAuth | | Multi-tenant | ❌ One DB per process | ⚠️ Single connection | ✅ N tenants per stack | | Tools available | ~6 RPC verbs | 20–40 | ✅ 197+ (92 native + 105 proxied) | | Memory / context layer | ❌ | ❌ | ✅ Qdrant vector + Ollama embeddings, per-user + shared | | Skills / orchestration | ❌ | ❌ | ✅ ai.skill records + memory packs | | Web terminal in browser | ❌ | ❌ | ✅ xterm.js + tmux + Claude Code | | GitHub / Portainer / Teams / OCA | ❌ | ❌ | ✅ 8 federated MCP servers | | Bulgaria localization | ❌ | ❌ | ✅ НАП-ready, fiscal positions, VAT | | Production deployment | DIY | Docker only | ✅ Docker Compose + K3s/Kustomize | | Audit logging / rate limit | ❌ | ⚠️ | ✅ Per-user logs, Cloudflare AI Gateway | | License | LGPL (client lib) | Mixed (some MIT, some commercial) | ✅ AGPL-3.0 (open, share-alike) |

The shorter version: most other MCP-Odoo bridges are great for "one developer wants to talk to one Odoo." odoo-claude-mcp is for teams, agencies, and SaaS providers that need multi-user, multi-database, audited deployments with a unified AI surface.

---

🎨 Use Cases

For Odoo Developers

• Live module development with Claude assisting directly on your running instance
• RPC-based module deployment — update code, views, data without filesystem access
• Multi-environment workflows — dev, staging, production from a single Claude session
• OCA contribution flows — clone, search, test, submit PRs through Claude

For Odoo Consultants

• Manage multiple client databases from one authenticated session
• Per-client memory — Claude remembers context for each customer
• Shared team knowledge — memory_share distributes institutional know-how
• НАП / Bulgaria localization — built-in tools for fiscal positions, VAT compliance

For Business Users

• "Ask Claude about our sales data" — natural language queries against real Odoo records
• Document extraction workflows — vision LLMs parse invoices into account.move
• Semantic search — find similar records, contracts, tickets across the whole database
• Email & calendar integration — Claude coordinates work across Odoo, Gmail, Calendar

For Platform Operators (SaaS / MSP)

• Multi-tenant hosting — each client gets an isolated MCP endpoint
• Billing integration — usage tracking per tenant via Cloudflare AI Gateway
• White-label terminals — brand claude-terminal for your customers
• Kubernetes scaling — scale MCP replicas independently based on load

---

🏗 Architecture

flowchart TD
    A["🧑 Claude.ai · Claude Code · Claude Desktop · IDE"]
    A -->|HTTPS + Bearer token| B
    subgraph GW["odoo-claude-mcp gateway"]
        B["Unified MCP Router · server.py<br/>• Proxies to 7 backend MCP servers<br/>• Per-user profiles &amp; connections<br/>• Shared memory store · audit log"]
    end
    B --> C1["odoo-rpc-mcp<br/>(core, 100+ tools)"]
    B --> C2["ee-mcp<br/>(Odoo EE)"]
    B --> C3["oca-mcp<br/>(OCA repos)"]
    B --> C4["github-mcp"]
    B --> C5["portainer-mcp"]
    B --> C6["filesystem-mcp"]
    B --> C7["teams-mcp"]
    B --> C8["claude-terminal<br/>(xterm.js + tmux)"]
    C1 --> D1["Odoo 15→19<br/>(N tenants)"]
    C1 --> D2["Qdrant<br/>(vector DB)"]
    C1 --> D3["Ollama<br/>(local LLMs)"]

    classDef gw fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b;
    classDef be fill:#f3f4f6,stroke:#6b7280,color:#111827;
    classDef st fill:#fef3c7,stroke:#d97706,color:#451a03;
    class B gw;
    class C1,C2,C3,C4,C5,C6,C7,C8 be;
    class D1,D2,D3 st;

---

🧰 MCP Servers

Core: odoo-rpc-mcp

The flagship MCP server. 197+ MCP tools (92 native + 105 proxied across Portainer, GitHub, Teams, EE, OCA, filesystem) covering every aspect of Odoo development and operations.

Capabilities:

• CRUD & Search: odoo_search_read, odoo_create, odoo_write, odoo_unlink, odoo_execute
• Introspection: odoo_fields_get, odoo_list_models, odoo_module_info
• Multi-connection: Switch between databases on the fly — odoo_connect, user_connection_activate
• Web session support: odoo_web_login, odoo_web_call, odoo_web_export, odoo_web_report
• File operations: odoo_attachment_upload, odoo_attachment_download, public_access_download
• Reporting: odoo_report, public_access_report_pdf, public_access_report_xlsx
• Portal access: public_access_portal_orders, public_access_portal_invoices, public_access_portal_tickets
• Bulgaria l10n: odoo_fp_configure, odoo_fp_list, odoo_fp_details — fiscal positions tailored for НАП compliance
• Translations ★ 2.10: odoo_list_translatable_fields, odoo_get_field_translations, odoo_translate_field (simple translate=True), odoo_translate_html (html_translate / xml_translate with extract/terms/replace modes). Version-aware (Odoo 16+ native JSONB API, <16 ir.translation fallback). Auto-ZWSP marks identical translations as "kept intentionally" so the website editor stops flagging them as untranslated.
• Website snippets ★ 2.10: odoo_website_list_snippets, odoo_website_list_page_snippets, odoo_website_add_snippet, odoo_website_update_snippet, odoo_website_remove_snippet. Lxml-based HTML parsing with xpath substitutions — covers blog posts, website pages (via arch_db), product descriptions, mega-menus. Supports background image swaps, CTA insertions, position-relative placement (end/begin/after/before/replace).
• AI integration: ai_tokenize_record, ai_search_similar, ai_collection_info — Qdrant vector embeddings per Odoo record
• Memory system: Per-user and shared memory with memory_read, memory_write, memory_share, memory_pull
• Google services: OAuth, Gmail search/read/send, Calendar CRUD
• Telegram: MTProto client — send messages, search contacts, read dialogs
• SSH & Git: Remote command execution, git operations

ee-mcp — Odoo Enterprise Tools

Tools specific to Odoo Enterprise workflows:

• License validation & status checks
• EE module repository management
• Dependency analysis (CE + EE)
• Selective EE module linking into CE addons paths
• Conflict detection between Enterprise and OCA modules

oca-mcp — OCA Module Management

Deep integration with the Odoo Community Associa