# Odoo Documentation MCP Server (`odoo-doc-mcp`)

[![Model Context Protocol](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blue.svg)](https://modelcontextprotocol.io/)
[![Odoo Multi-Version](https://img.shields.io/badge/Odoo-v15.0%20%7C%20v16.0%20%7C%20v17.0%20%7C%20v18.0%20%7C%20v19.0-purple.svg)](https://www.odoo.com/documentation/)
[![Python Version](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Transport](https://img.shields.io/badge/Transport-SSE%20%7C%20HTTP%20%7C%20STDIO-orange.svg)](#-running-the-mcp-server)

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](#-features--highlights)
- [🌐 Connecting Web AI Chatbots via Public Tunnel (ngrok / Cloudflare / localtunnel)]
- [💬 Ready-to-Use Prompt Examples Library](#-ready-to-use-prompt-examples-library)
- [🛠️ Installation & Setup Guide](#️-installation--setup-guide)
- [🚀 Running the MCP Server](#-running-the-mcp-server)
- [🤖 AI Client Configuration (Cursor, Claude, ChatGPT)](#-ai-client-configuration-cursor-claude-chatgpt)
- [💡 How Non-Technical & Technical Users Ask Questions](#-how-non-technical--technical-users-ask-questions)
- [🛠️ MCP Tools Reference](#️-mcp-tools-reference)
- [🧪 Running Automated Tests](#-running-automated-tests)
- [🏗️ Project Architecture](#️-project-architecture)
- [📄 License & Author](#-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):
   ```bash
   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**:
   ```bash
   python -m odoo_doc_mcp.server --transport sse --port 8008 --host 0.0.0.0
   ```

3. **Expose port 8008 with ngrok**:
   ```bash
   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:
   ```text
   https://a1b2c3d4.ngrok-free.app/sse
   ```

---

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

1. **Install cloudflared**:
   ```bash
   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**:
   ```bash
   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:
   ```text
   https://your-tunnel-name.trycloudflare.com/sse
   ```

---

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

```bash
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

```bash
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

```bash
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)

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

---

## 🤖 AI Client Configuration (Cursor, Claude, ChatGPT)

### 1. Cursor IDE (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "odoo-doc": {
      "url": "http://localhost:8008/sse"
    }
  }
}
```

### 2. Online AI Chatbot / Cloud Agent (via ngrok)
```json
{
  "mcpServers": {
    "odoo-doc": {
      "url": "https://a1b2c3d4.ngrok-free.app/sse"
    }
  }
}
```

### 3. Claude Desktop (`claude_desktop_config.json`)
```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

```bash
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`