Odoo Documentation MCP Server (odoo-doc-mcp)

The ultimate Model Context Protocol (MCP) server for All Odoo Versions (v15.0 to v19.0+). Connect your AI assistants (Cursor IDE, Claude Desktop, ChatGPT Web, Custom Web AI Chatbots, Windsurf) directly to live, official Odoo user and developer documentation in clean, LLM-optimized Markdown format.

---

📌 Table of Contents

• ✨ Features & Highlights
• [🌐 Connecting Web AI Chatbots via Public Tunnel (ngrok / Cloudflare / localtunnel)]
• 💬 Ready-to-Use Prompt Examples Library
• 🛠️ Installation & Setup Guide
• 🚀 Running the MCP Server
• 🤖 AI Client Configuration (Cursor, Claude, ChatGPT)
• 💡 How Non-Technical & Technical Users Ask Questions
• 🛠️ MCP Tools Reference
• 🧪 Running Automated Tests
• 🏗️ Project Architecture
• 📄 License & Author

---

✨ Features & Highlights

• 🔄 Universal Multi-Version Support (v15.0 - v19.0+): Seamlessly fetch documentation for any Odoo release version (15.0, 16.0, 17.0, 18.0, 19.0, or master).
• 🌐 Web AI Chatbot Ready (ngrok & Cloudflare Tunnels): Includes step-by-step guides to expose local SSE endpoints to online cloud AI tools (ChatGPT Web, Custom AI Chatbots) over HTTPS.
• 🚀 Deep All-in-One Search (search_and_fetch_docs): Automatically searches the index AND fetches the FULL Markdown text of all matching articles in parallel.
• 📚 Recursive Master Section Exporter (get_doc_section): Discovers all subpages in a documentation section (e.g. CRM, Accounting, Inventory, ORM, Views) and downloads them in parallel, merging everything into one master document.
• 📖 100% Official Live Odoo Docs: Dynamically fetches live content directly from https://www.odoo.com/documentation/. Zero stale static files.
• 🔓 Full CORS Enabled: Built-in CORSMiddleware (Access-Control-Allow-Origin: *) for browser-based AI clients.
• ⚡ Local Disk Caching & SQLite FTS5: Superfast full-text search with disk-cached Markdown responses.

---

🌐 Connecting Web AI Chatbots via Public Tunnel (ngrok / Cloudflare / localtunnel)

Web-based AI Chatbots (such as ChatGPT Web, Custom Web AI Agents, Cloud LLMs) run on external servers and cannot access http://localhost:8008/sse directly.

To connect an online AI Chatbot to your local MCP server, expose your server port using a secure HTTPS tunnel tool:

Method 1: Using ngrok (Recommended)

1. Install ngrok (if not installed):

   curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
   echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list
   sudo apt update && sudo apt install ngrok
   

2. Start the Odoo MCP Server locally:

   python -m odoo_doc_mcp.server --transport sse --port 8008 --host 0.0.0.0
   

3. Expose port 8008 with ngrok:

   ngrok http 8008
   

4. Copy your Public HTTPS SSE URL: ngrok will generate a public URL like https://a1b2c3d4.ngrok-free.app. Your Public SSE URL to give to your AI Chatbot is:

   https://a1b2c3d4.ngrok-free.app/sse
   

---

Method 2: Using Cloudflare Tunnel (cloudflared - 100% Free)

1. Install cloudflared:

   sudo wget -q https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
   sudo dpkg -i cloudflared-linux-amd64.deb
   

2. Launch Cloudflare Tunnel:

   cloudflared tunnel --url http://localhost:8008
   

3. Copy your TryCloudflare HTTPS SSE URL: Cloudflare will output a URL like https://your-tunnel-name.trycloudflare.com. Your Public SSE URL is:

   https://your-tunnel-name.trycloudflare.com/sse
   

---

Method 3: Using localtunnel (Node.js / npm)

npx localtunnel --port 8008

Your Public SSE URL will be: https://your-custom-subdomain.loca.lt/sse

---

💬 Ready-to-Use Prompt Examples Library

Copy and paste these example prompts into your AI assistant:

👤 Non-Technical Business User Prompts

• 💬 "How do I track lost sales opportunities in Odoo CRM, and how can I generate a report to analyze why we lost them?"
• 💬 "What is the step-by-step process for recording vendor bills and matching them with bank payments in Odoo Accounting?"
• 💬 "How do I transfer stock between two different internal warehouses in Odoo Inventory?"

👔 Odoo Functional Consultant Prompts

• 💬 "Using the Odoo Doc server for Odoo 19.0, explain how Chart of Accounts, Journals, and Tax Grids interact during invoice validation."
• 💬 "Explain the difference between Automated and Manual Inventory Valuation in Odoo 18.0 with real-world accounting entries."

💻 Odoo Backend Developer Prompts

• 💬 "Fetch the Odoo ORM documentation (developer/reference/backend/orm.html) for Odoo 19.0 and give me examples of @api.depends, @api.constrains, and @api.onchange."
• 💬 "Search Odoo docs for model inheritance (_inherit vs _inherits) and explain how parent field delegation works."

🎨 Odoo Frontend & View Developer Prompts

• 💬 "Using Odoo Doc MCP, search for XML View Syntax (developer/reference/user_interface/view_records.html) and explain list view <list> attributes and form view tab structures (<notebook>)."
• 💬 "How do I create a custom OWL component in Odoo 18.0 JavaScript framework?"

🔄 Odoo Version Migration Prompts

• 💬 "Search Odoo 19.0 docs for view changes and list view <list> tag deprecations compared to older tree view tags."

---

🎯 SEO Keywords & Supported Topics

💼 Odoo Functional Modules (v15.0 - v19.0)

• Odoo Accounting & Invoicing: Chart of Accounts, Journals, Customer Invoices, Vendor Bills, Payment Gateways, Tax Returns, Bank Reconciliation, Year-End Closing, Financial Reports.
• Odoo CRM & Sales: Lead Management, Opportunities Pipeline, Lead Mining, Predictive Lead Scoring, Quotations, Sales Teams.
• Odoo Inventory & MRP: Warehouse Management, Stock Transfers, Product Tracking (Lots & Serials), Inventory Valuation, Reordering Rules, Manufacturing Orders (BOM).
• Odoo POS, eCommerce, HR, Project, & Purchasing.

💻 Odoo Technical & Developer Documentation

• Odoo Server Framework 101: Module Structure, Manifest Files (__manifest__.py).
• Odoo ORM Reference: Models (models.Model), Fields (Char, Many2one, One2many, Many2many), Compute Methods, SQL Constraints.
• Odoo UI Views Syntax: List Views (<list>), Form Views (<form>, <sheet>, <group>), Search Views (<search>, <filter>), Kanban Views, Pivot Views.
• Domains & Security: Domain criteria expressions ([('state', '=', 'posted')]), Record Rules (ir.rule), Access Rights (ir.model.access.csv).
• JavaScript & OWL Framework: OWL Components, Web Client, JS Views, Widgets, Controllers.

---

🛠️ Installation & Setup Guide

1. Prerequisites

• Python 3.10+ (Python 3.12 recommended)
• pip and virtualenv

2. Set Up Virtual Environment

cd odoo-doc-mcp

# Create virtual environment if not created
python3 -m venv .venv

# Activate virtual environment
source .venv/bin/activate

# Install dependencies
pip install -e .

---

🚀 Running the MCP Server

Local HTTP / SSE Server Mode

source .venv/bin/activate
python -m odoo_doc_mcp.server --transport sse --port 8008 --host 0.0.0.0

STDIO Transport Mode (Desktop AI Apps)

source .venv/bin/activate
python -m odoo_doc_mcp.server --transport stdio

---

🤖 AI Client Configuration (Cursor, Claude, ChatGPT)

1. Cursor IDE (.cursor/mcp.json)

{
  "mcpServers": {
    "odoo-doc": {
      "url": "http://localhost:8008/sse"
    }
  }
}

2. Online AI Chatbot / Cloud Agent (via ngrok)

{
  "mcpServers": {
    "odoo-doc": {
      "url": "https://a1b2c3d4.ngrok-free.app/sse"
    }
  }
}

3. Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "odoo-doc": {
      "command": "/path/to/odoo-doc-mcp/.venv/bin/python",
      "args": [
        "-m",
        "odoo_doc_mcp.server",
        "--transport",
        "stdio"
      ]
    }
  }
}

---

🛠️ MCP Tools Reference

Tool Name	Parameters	Description
search_and_fetch_docs	query, version='18.0', max_results=3	Deep All-in-One Search: Searches index AND auto-fetches full Markdown text for all matches in parallel.
get_doc_section	path, version='18.0', recursive=True, max_pages=25	Recursive Master Exporter: Downloads an entire section and all child subpages in parallel into one document.
get_complete_docs	topic, version='18.0', max_pages=30	Export complete documentation for an entire module domain (CRM, Accounting, Sales, Inventory, ORM).
get_learning_module	topic, version='18.0'	Generates a structured learning module with official unedited documentation text.
get_doc_page	path, version='18.0'	Fetch and convert a single Odoo documentation page into clean Markdown.
search_odoo_docs	query, version='18.0', category, max_results=3	Search documentation topics by keyword with full content auto-fetching.
list_doc_topics	version='18.0', category	Browse available Odoo documentation topics and category hierarchy.
refresh_index	version='18.0'	Re-fetch the live Table of Contents HTML and update the SQLite search index.

---

🧪 Running Automated Tests

source .venv/bin/activate
pytest tests/

---

🏗️ Project Architecture

odoo-doc-mcp/
├── odoo_doc_mcp/
│   ├── __init__.py
│   ├── server.py        # FastMCP & Universal Starlette HTTP/SSE Controller
│   ├── fetcher.py       # Async HTTP fetcher, parallel section crawler & caching
│   ├── parser.py        # HTML to Markdown converter & TOC link extractor
│   ├── indexer.py       # SQLite FTS5 full-text search index manager
│   └── seed_data.py     # Fallback offline navigation TOC seed
├── tests/
│   └── test_server.py   # Pytest test suite
├── pyproject.toml       # Project metadata & dependencies
├── README.md            # Master documentation & SEO guide
└── .gitignore          # Repository ignore rules

---

🏷️ Tags & Keywords

#odoo #mcp #model-context-protocol #odoo15 #odoo16 #odoo17 #odoo18 #odoo19 #odoo-documentation #cursor-ide #claude-desktop #chatgpt-mcp #ngrok #cloudflare-tunnel #python #ai-agent #pair-programming #odoo-developer #odoo-accounting #odoo-crm