Skip to main content
Glama
SantipBarber

AI-OdooFinder

by SantipBarber
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid
README.md
# 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">

![AI-OdooFinder Banner](docs/logo-banner.svg)

[![PyPI version](https://img.shields.io/pypi/v/ai-odoofinder-mcp.svg)](https://pypi.org/project/ai-odoofinder-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Odoo](https://img.shields.io/badge/Odoo-10.0%20to%2019.0-714B67)](https://www.odoo.com)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green)](https://modelcontextprotocol.io/)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/SantipBarber/ai-odoo-finder)


**Language**: [English](README.md) | [Español](README.es.md)

</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](https://pypi.org/project/ai-odoofinder-mcp/). Add the following config to your MCP client:

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

> **Note**: Requires [uv](https://docs.astral.sh/uv/) package manager installed.

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

For the latest development version:

```json
{
  "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`

```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:
```bash
npm install -g @anthropic-ai/claude-code
```

Add MCP server:
```bash
# Interactive setup
claude mcp add

# Or edit ~/.claude.json directly
```

Configuration (`~/.claude.json`):
```json
{
  "mcpServers": {
    "ai-odoofinder": {
      "command": "uvx",
      "args": ["ai-odoofinder-mcp"],
      "env": {
        "AI_ODOOFINDER_API_URL": "https://strategy-orchestrator-prod.tailf7d690.ts.net"
      }
    }
  }
}
```

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

```json
{
  "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):

```json
{
  "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`:

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

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

```json
{
  "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)**

```json
{
  "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:
```bash
where uvx  # Windows
which uvx  # macOS/Linux
```

```json
{
  "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](docs/en/MCP_CLIENT_CONFIGURATIONS.md#antigravity)

</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](docs/en/MCP_CLIENT_CONFIGURATIONS.md)

</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](docs/en/MCP_CLIENT_CONFIGURATIONS.md)

---

### Deploy Your Own Instance

See [docs/en/DEPLOYMENT_OPERATIONS.md](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

```bash
# 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](https://santipbarber.github.io/ai-odoo-finder/showcase/) - Visual presentation of the project
- [MCP Client Configurations](docs/en/MCP_CLIENT_CONFIGURATIONS.md) - Complete guide for all MCP clients
- [Deployment & Operations](docs/en/DEPLOYMENT_OPERATIONS.md) - Deployment and operations guide
- [Project History](docs/en/PROJECT_HISTORY.md) - Evolution of the project architecture
- [Changelog](docs/en/CHANGELOG.md) - Change history
- [MCP Server README](mcp-server/README.md) - MCP server installation and configuration

---

## Development

### Requirements

- Python 3.13+
- [uv](https://docs.astral.sh/uv/) (dependency manager)
- Docker (for local PostgreSQL)

### Local Setup

```bash
# 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](LICENSE)

---

## Author

**Santiago Perez Barber**
- GitHub: [@SantipBarber](https://github.com/SantipBarber)
- LinkedIn: [santipbarber](https://linkedin.com/in/santipbarber)

---

## Acknowledgments

- [Odoo Community Association (OCA)](https://odoo-community.org/) - For their open source work
- [Anthropic](https://www.anthropic.com/) - For Claude and the MCP protocol

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources