AI-OdooFinder

Find the perfect Odoo module with AI in seconds.

An MCP (Model Context Protocol) server that enables LLMs to search Odoo modules in OCA repositories using hybrid search (semantic + full-text).

<div align="center">

Language: English | Español

</div>

---

The Problem

As an Odoo developer:

• You build features that already exist in OCA
• You spend hours searching for the right module on GitHub
• You install modules incompatible with your version
• You discover abandoned modules after integration

---

The Solution

AI-OdooFinder provides:

• Hybrid Search: Combines semantic search (embeddings) with BM25 full-text
• Version Filtering: Only shows compatible modules (10.0 to 19.0)
• AI Enrichment: Descriptions, tags and keywords generated by Grok-4-fast
• MCP Integration: Use directly from Claude Desktop or Claude.ai

---

Architecture

┌─────────────────────┐      ┌──────────────────────────────────────┐
│  Claude.ai Web      │      │        Hetzner VPS (Docker)          │
│  Zed / Cursor       │─────►│  ┌─────────────┐  ┌──────────────┐   │
│  (remote MCP)       │ HTTPS│  │ MCP Server  │  │   FastAPI    │   │
└─────────────────────┘      │  │  :8080/mcp  │─►│   :8989      │   │
                             │  └─────────────┘  └──────┬───────┘   │
┌─────────────────────┐      │                          │           │
│   Claude Desktop    │      │                   ┌──────▼───────┐   │
│   + MCP Server      │─────►│                   │  PostgreSQL  │   │
│   (local, STDIO)    │ HTTPS│                   │  + pgvector  │   │
└─────────────────────┘      │                   └──────────────┘   │
                             └──────────────────────────────────────┘

Usage modes:

• Remote MCP (Claude.ai Web, Zed, Cursor): Connect to remote MCP Server via HTTP
• Local MCP (Claude Desktop): MCP Server runs locally via STDIO
• Direct REST API: For custom integrations

Components:

• MCP Server HTTP (remote, :8080): MCP server for remote clients
• FastAPI Backend (remote, :8989): REST API with hybrid search
• PostgreSQL + pgvector (remote): 16,494 modules with embeddings

---

Statistics

Metric	Value
Indexed Modules	16,494
Odoo Versions	10 (v10.0 - v19.0)
OCA Repositories	244
With AI Enrichment	100%
Response Time	< 500ms

Modules by Version

Version	Modules
10.0	2,312
11.0	2,105
12.0	2,215
13.0	1,990
14.0	2,886
15.0	2,074
16.0	2,886
17.0	1,699
18.0	2,022
19.0	112

---

Installation

The MCP server is available on PyPI. Add the following config to your MCP client:

{
  "mcpServers": {
    "ai-odoofinder": {
      "command": "uvx",
      "args": ["ai-odoofinder-mcp"],
      "env": {
        "AI_ODOOFINDER_API_URL": "https://strategy-orchestrator-prod.tailf7d690.ts.net"
      }
    }
  }
}

Note: Requires uv package manager installed.

<details> <summary><b>Alternative: Install from Git (development)</b></summary>

For the latest development version:

{
  "mcpServers": {
    "ai-odoofinder": {
      "command": "uvx",
      "args": ["ai-odoofinder-mcp"],
      "env": {
        "AI_ODOOFINDER_API_URL": "https://strategy-orchestrator-prod.tailf7d690.ts.net"
      }
    }
  }
}

</details>

IDE/Client Configuration

<details> <summary><b>Claude Desktop</b></summary>

Add to claude_desktop_config.json:

File locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "ai-odoofinder": {
      "command": "uvx",
      "args": ["ai-odoofinder-mcp"],
      "env": {
        "AI_ODOOFINDER_API_URL": "https://strategy-orchestrator-prod.tailf7d690.ts.net"
      }
    }
  }
}

Restart Claude Desktop.

</details>

<details> <summary><b>Claude Code CLI</b></summary>

NEW! Use Claude directly from your terminal.

Install Claude Code:

npm install -g @anthropic-ai/claude-code

Add MCP server:

# Interactive setup
claude mcp add

# Or edit ~/.claude.json directly

Configuration (~/.claude.json):

{
  "mcpServers": {
    "ai-odoofinder": {
      "command": "uvx",
      "args": ["ai-odoofinder-mcp"],
      "env": {
        "AI_ODOOFINDER_API_URL": "https://strategy-orchestrator-prod.tailf7d690.ts.net"
      }
    }
  }
}

Usage:

claude
> I need an Odoo 17 module for subscriptions

</details>

<details> <summary><b>Claude.ai Web (Remote)</b></summary>

No installation required. Connect directly:

1. Go to Claude.ai > Settings > Connectors
2. Click "Add custom connector"
3. Enter the MCP server URL:

   https://strategy-orchestrator-prod.tailf7d690.ts.net/mcp
   

4. Save and start searching

Protocol: Streamable HTTP (MCP spec 2024-11-05)

</details>

<details> <summary><b>ChatGPT Developer Mode</b></summary>

NEW! OpenAI added full MCP support in September 2025.

Requirements:

• ChatGPT Plus/Pro/Team subscription
• Developer Mode enabled (beta)

Setup:

1. Go to ChatGPT Settings > Beta Features
2. Enable "Developer Mode"
3. Navigate to Integrations > MCP Servers
4. Add server:
   • Remote (easiest): https://strategy-orchestrator-prod.tailf7d690.ts.net/mcp
   • Local: Use uvx configuration (see full docs)

Usage:

Use ai-odoofinder to find Odoo 17 modules for inventory

Note: Supports both read and write operations (not read-only).

</details>

<details> <summary><b>VSCode Copilot</b></summary>

NEW! GitHub Copilot supports MCP (GA since July 2025).

Requirements:

• VSCode 1.102+
• GitHub Copilot subscription
• MCP policy enabled (Business/Enterprise only)

Configuration:

Create .vscode/mcp.json (project) or ~/.config/Code/User/mcp.json (global):

{
  "servers": {
    "ai-odoofinder": {
      "type": "stdio",
      "command": "uvx",
      "args": ["ai-odoofinder-mcp"],
      "env": {
        "AI_ODOOFINDER_API_URL": "https://strategy-orchestrator-prod.tailf7d690.ts.net"
      }
    }
  }
}

Reload VSCode (Ctrl/Cmd + Shift + P → "Reload Window").

Usage:

@workspace Find an Odoo module for accounting

For Business/Enterprise: Admin must enable "MCP servers in Copilot" policy.

</details>

<details> <summary><b>Cursor</b></summary>

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "ai-odoofinder": {
      "command": "uvx",
      "args": ["ai-odoofinder-mcp"],
      "env": {
        "AI_ODOOFINDER_API_URL": "https://strategy-orchestrator-prod.tailf7d690.ts.net"
      }
    }
  }
}

Restart Cursor.

</details>

<details> <summary><b>Zed</b></summary>

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "ai-odoofinder": {
      "command": "uvx",
      "args": ["ai-odoofinder-mcp"],
      "env": {
        "AI_ODOOFINDER_API_URL": "https://strategy-orchestrator-prod.tailf7d690.ts.net"
      }
    }
  }
}

Or use Add Server in Zed's Agent Panel with this JSON:

{
  "ai-odoofinder": {
    "command": "uvx",
    "args": ["ai-odoofinder-mcp"],
    "env": {
      "AI_ODOOFINDER_API_URL": "https://strategy-orchestrator-prod.tailf7d690.ts.net"
    }
  }
}

Restart Zed.

</details>

<details> <summary><b>Windsurf</b></summary>

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "ai-odoofinder": {
      "command": "uvx",
      "args": ["ai-odoofinder-mcp"],
      "env": {
        "AI_ODOOFINDER_API_URL": "https://strategy-orchestrator-prod.tailf7d690.ts.net"
      }
    }
  }
}

Restart Windsurf.

</details>

<details> <summary><b>Antigravity</b></summary>

⚠️ Known Issues: Antigravity has compatibility problems with uvx and remote MCP connections.

Solution 1: Use npx (Recommended)

{
  "mcpServers": {
    "ai-odoofinder": {
      "command": "npx",
      "args": [
        "-y",
        "@SantipBarber/ai-odoofinder-mcp"
      ],
      "env": {
        "AI_ODOOFINDER_API_URL": "https://strategy-orchestrator-prod.tailf7d690.ts.net"
      }
    }
  }
}

Solution 2: Use full path to uvx (Windows)

Find your uvx path:

where uvx  # Windows
which uvx  # macOS/Linux

{
  "mcpServers": {
    "ai-odoofinder": {
      "command": "C:\\Users\\YOUR_USER\\.cargo\\bin\\uvx.exe",
      "args": ["ai-odoofinder-mcp"],
      "env": {
        "AI_ODOOFINDER_API_URL": "https://strategy-orchestrator-prod.tailf7d690.ts.net"
      }
    }
  }
}

Known Limitations:

• ❌ Remote mode NOT supported (SSE protocol incompatibility)
• ⚠️ May stall with remote connections
• ✅ Local mode works with workarounds above

See full troubleshooting: MCP Client Configurations

</details>

<details> <summary><b>Other MCP Clients</b></summary>

For any MCP-compatible client:

Local mode (STDIO): Use the configuration shown above

Remote mode (HTTP): Use the server URL:

https://strategy-orchestrator-prod.tailf7d690.ts.net/mcp

Protocol: Streamable HTTP (MCP spec 2024-11-05)
Authentication: None (public server)

Full configuration guide: MCP Client Configurations

</details>

---

Client Compatibility Matrix

Client	Local	Remote	Status	Notes
Claude Desktop	✅	❌	Stable	Best experience
Claude Code CLI	✅	✅	Stable	NEW! Terminal-based
Claude.ai Web	❌	✅	Stable	Zero install
ChatGPT Dev Mode	✅	✅	Beta	NEW! Sept 2025
VSCode Copilot	✅	⚠️	GA	NEW! July 2025
Cursor	✅	❌	Stable	Popular choice
Zed	✅	❌	Stable	Fast editor
Windsurf	✅	❌	Stable	Full support
Antigravity	⚠️	❌	Issues	Use npx/workarounds

Legend:

• ✅ Fully supported
• ⚠️ Partial support / workarounds needed
• ❌ Not supported

Full details: See MCP Client Configurations

---

Deploy Your Own Instance

See docs/en/DEPLOYMENT_OPERATIONS.md for Docker deployment instructions.

---

Usage

From Claude Desktop (MCP)

Simply ask in natural language:

"I need a module for Odoo 17 that handles recurring payments"

Claude will use the MCP Server to search and show you the results.

Direct REST API

# Health check
curl https://strategy-orchestrator-prod.tailf7d690.ts.net/health

# Search
curl "https://strategy-orchestrator-prod.tailf7d690.ts.net/search?query=subscription&version=17.0&limit=5"

# Statistics
curl https://strategy-orchestrator-prod.tailf7d690.ts.net/stats

---

Tech Stack

Component	Technology
Backend	FastAPI (Python 3.13+)
Database	PostgreSQL 17 + pgvector
Embeddings	Qwen3-Embedding-4B via OpenRouter
Enrichment	Grok-4-fast via OpenRouter
MCP Server	FastMCP (Python)
Containers	Docker + Docker Compose
Hosting	Hetzner VPS (ARM64)
Tunnel	Tailscale Funnel (HTTPS)

---

Documentation

• Interactive Showcase - Visual presentation of the project
• MCP Client Configurations - Complete guide for all MCP clients
• Deployment & Operations - Deployment and operations guide
• Project History - Evolution of the project architecture
• Changelog - Change history
• MCP Server README - MCP server installation and configuration

---

Development

Requirements

• Python 3.13+
• uv (dependency manager)
• Docker (for local PostgreSQL)

Local Setup

# Clone
git clone https://github.com/SantipBarber/ai-odoo-finder.git
cd ai-odoo-finder

# Install dependencies
uv sync

# Configure variables
cp .env.example .env
# Edit .env with your credentials

# Start PostgreSQL
docker compose up -d db

# Run ETL (index modules)
uv run python scripts/etl_oca_modules.py

# Start API
uv run uvicorn backend.app.main:app --port 8989

---

License

MIT - See LICENSE

---

Author

Santiago Perez Barber

• GitHub: @SantipBarber
• LinkedIn: santipbarber

---

Acknowledgments

• Odoo Community Association (OCA) - For their open source work
• Anthropic - For Claude and the MCP protocol