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.
Self-hosted MCP server connecting Claude to Odoo 15→19 — 197+ tools, multi-tenant, Bulgaria l10n
星數
51
工具
—
可用率
—
Connect Claude, Claude Code, and any MCP-compatible client to Odoo, GitHub, filesystem, Portainer, Teams, and more — through a unified, authenticated gateway.
Two tracks. You are on branch 3.0 — the preview track for integrators, current v3.3.8. The stable track is branch 2.0, current v2.31.0. All releases: Releases · details in Two Tracks.
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.
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
"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 & 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.
filesystem-mcp — Scoped filesystem operations for AI agents
📦 Companion Odoo Modules & Theme
The MCP stack is paired with several Odoo modules and a website
theme. Together they turn any Odoo instance into a fully MCP-aware,
multi-tenant, billing-ready AI workstation — with an optional editorial
website skin on top.
Odoo module that exposes MCP + Claude Terminal configuration as user
preferences and company settings. Works on Odoo 16, 18 and 19 (each
major series has a dedicated branch).
🌍 Non-Bulgarian deployments? Use the international fork
rosenvladimirov/odoo-mcp-terminal
— same module, redistributed without the BG localization
dependencies (no НАП fields, no Bulgarian transliteration mixin).
Branches 16.0 / 18.0 / 19.0, AGPL-3.0. Recommended for any
Odoo instance outside Bulgaria.
Vertical timeline language switcher — replaces Odoo's default
language dropdown with a sidebar timeline (works well for trilingual
EN / BG / RU sites)
Editorial typography — measured for long-form posts, runs ≤ 70
chars per line, optimised vertical rhythm
Fully #wrapwrap-scoped — no leakage into Odoo backend or
Website Builder editor (avoids the $o-color-palettes-name global
leak that breaks editor UI in older themes)
Installable on any Odoo 19 instance. Drop it into your addons path,
install via Apps, then assign in Website → Configuration → Themes.
Installation order
odoo-mcp-theme ← optional: editorial website skin
l10n_bg_claude_terminal ← every user of the MCP terminal
↓
l10n_bg_ai_billing ← hosting providers / resellers / BL-tier ops
l10n_bg_ai_billing depends on l10n_bg_claude_terminal — installing
the billing module auto-pulls the terminal integration.
odoo-mcp-theme is independent and can be used with or without the
MCP stack.
No credentials in code — all secrets via environment variables or Kubernetes secrets
Token-based MCP auth — no shared passwords
Per-user data isolation — filesystem and memory scoped to authenticated user
OAuth for third-party services — Google, GitHub, Telegram all use standard OAuth flows
Connection encryption — HTTPS/WSS everywhere in production deployments
Rate limiting — via Cloudflare AI Gateway or ingress controller
Audit logging — all MCP tool calls logged with user context
Admin console behind a second factor — TOTP (RFC 6238) with one-time recovery codes,
optional MCP_ADMIN_REQUIRE_TOTP policy, every session-issuing path gated ★ new in 3.3.8 (see below)
Reporting security issues: please email [email protected] rather than opening a public issue.
Admin console (/admin)
A hidden web console inside odoo-rpc-mcp for the people who operate a
stack: per-user Odoo connections, user provisioning with one-time keys,
backups and filestore. Optional and off unless configured.
Env
Meaning
MCP_ADMIN_PATH_PREFIX
Mount path, default /admin; empty disables the console
MCP_BOOTSTRAP_ADMIN
Odoo login that becomes admin on first sign-in
MCP_SECRET_TOKEN / MCP_ADMIN_SESSION_SECRET
Signs session cookies. Required — the console refuses to mount without one
MCP_KEY_PEPPER
≥32 chars. Encrypts TOTP secrets at rest (same pepper as identify_totp_*)
MCP_ADMIN_REQUIRE_TOTP
admins or all — hold users in scope on the Security page until they enrol a second factor
MCP_ADMIN_KNOCK_TOKEN, MCP_ADMIN_ALLOWED_IPS
Optional knock token (?k=) and IP/CIDR allowlist
Second factor. Each user enrols TOTP from Security: password → QR →
confirming code → eight one-time recovery codes. Once enrolled, every way of
obtaining a session (MCP password, Odoo re-auth, one-time key) asks for the
code. Secrets live in /data/users/<login>/totp.json; an admin can reset a
user's factor from Users, and the last admin recovers by deleting that file
on the volume. Everything is written to /data/admin_audit.log — never the
secret or a code.
🌍 Bulgaria Localization
This project is maintained by the OCA l10n-bulgaria maintainer. Bulgarian-specific features are first-class:
НАП integration — fiscal position tax action maps, VAT reports
l10n_bg_* module family support — fiscal positions, VAT reports, payroll, HR
Образец 1 — monthly NAP declaration (Наредба №Н-13/2019)
Bulgarian partner identification — UIC/ЕИК, legal forms, NACE activity codes
Transliteration — BG ⇄ EN ⇄ GR mixin for partner names
НАП справка-декларация — SQL-engine based audit reports
Does it work with Odoo Enterprise?
Yes. Odoo 15→19 (Community + Enterprise) are all supported via XML-RPC + JSON-RPC. EE-specific tools (license check, EE module discovery, dependency analysis) live in the dedicated ee-mcp server. No Odoo SH-specific hooks — works on any self-hosted Odoo (bare metal, Docker, K3s, Odoo SH outbound).
Is this OCA-approved / on the Odoo Apps Store?
The companion modules (l10n_bg_claude_terminal, the broader l10n-bulgaria family) are maintained by the OCA l10n-bulgaria maintainer. The MCP server itself is an independent project (not an Odoo app), AGPL-3.0, distributed via Docker Hub + GitHub. Track 3.x will publish a SaaS billing module on the Odoo Apps Store separately.
BYOK (bring your own Anthropic key) — is it safe?
Yes. Each authenticated user can configure their own Anthropic API key via the Odoo UI (Preferences → Claude Terminal). Keys are stored encrypted in the per-user profile (/data/users/{username}/) and never leak to other tenants. The server never bundles a shared Anthropic key into multi-tenant deployments.
Can one stack serve multiple Odoo databases?
Yes — that's the core design. One MCP server instance proxies to N Odoo connections, each with its own credentials, language, and timezone. odoo_connect / user_connection_activate switch the active database mid-session. Per-user memory namespaces keep context isolated.
Does it require Cloudflare?
No. Cloudflare is the recommended production topology (Tunnel + WAF + AI Gateway), but the stack runs fine behind any reverse proxy (Nginx, Traefik, Caddy) or directly on a LAN/VPN. The docker-compose.local.yml override removes the Cloudflare network requirement for local dev.
What's the difference between this and Rutger Klabbers's odoo-mcp-pro?
Different scope. odoo-mcp-pro is a focused single-user/single-DB Odoo MCP wrapper. odoo-claude-mcp is a multi-tenant gateway with 7+ federated MCP servers (Odoo + GitHub + OCA + Portainer + filesystem + Teams + claude-terminal), per-user authentication, audit logging, and a companion Odoo billing module for SaaS providers. Both projects are open source — pick the one that matches your deployment shape.
Can I run only the parts I need?
Yes. Compose profiles gate optional services: docker compose up -d starts only the core (no Portainer, no Teams). Use --profile portainer / --profile teams / --profile full to add them. K3s overlays are similarly modular.
🛤 Two Tracks — Which Branch Do You Want?
This project ships on two parallel branches, each targeting a different
audience. Most users want Track 2.x; the 3.x track is for integrators
building hosted offerings on top of the stack.
🧑💼 Track 2.x — End Users (current stable, branch 2.0)
Who: Odoo end-users, accountants, Bulgarian SMEs, developers who work
with a single Odoo stack, content teams managing website/blog.
What you get:
All 188+ MCP tools for day-to-day Odoo work (CRUD, search, RPC,
introspection, attachments, reports, web session)
Multi-language field management (odoo_translate_field +
odoo_translate_html + 2 helpers — covers blog.post, product
descriptions, website pages, arch_db) ★ new in 2.10
Website snippet management (list / add / update / remove
snippets on blog posts and pages, with background image swaps and
substitutions) ★ new in 2.10
Industry skill packs — Manufacturing, Retail, Services, BG
Localization, AI Accounting Assistant. Each pack = modules +
ai.skill records + memory packs + pipeline steps.
Demo builder — one-command generator of fresh demo
environments (mcp demo create --industry=... --seed=...).
Tenant + Odoo DB + demo data + skills + memory in < 5 minutes.
Module dev + test toolkit — odoo_module_scaffold / lint / test / install_from_path / explain, odoo_xml_validate.
Already shipping on 3.x: self-service provisioning (/provision), supervisor + fleet
tools, OAuth hardening with mandatory PKCE (3.3.6), TOTP second factor for MCP
name-identify (3.3.0) and for the admin console (3.3.8, see Security above).
Docker tags::next, :3.x.y (current: 3.3.8)
Documentation:docs/integrator-platform.md
(coming soon — see project memory roadmap_integrator_platform.md
for the full 4-track spec)
Positioning: the 3.x track shifts buyer persona from the final
Odoo user to the integrator / partner / agency — giving them the
tools to deploy, configure, and demo Odoo + AI workflows for their
own clients at scale.