# 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-14.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 (12.0 to 19.0)
- **AI Enrichment**: Descriptions, tags and keywords generated by Grok-4-fast
- **MCP Integration**: Use it from Claude, ChatGPT, Cursor, VS Code, Zed... via a public URL

---

## Architecture

```
┌──────────────────────────┐         ┌───────────────────────────────────────┐
│  Claude.ai / Desktop     │         │   Eticco infrastructure (Docker)      │
│  Claude Code · ChatGPT   │  HTTPS  │  ┌──────────────┐   ┌─────────────┐   │
│  Cursor · VS Code · Zed  │────────►│  │  MCP Server  │──►│   FastAPI   │   │
│  Windsurf · ...          │         │  │ (Streamable  │   │   backend   │   │
└──────────────────────────┘         │  │    HTTP)     │   └──────┬──────┘   │
   https://addon-finder.eticco.es    │  └──────────────┘          │          │
                                     │                     ┌──────▼──────┐   │
                                     │                     │ PostgreSQL  │   │
                                     │                     │ + pgvector  │   │
                                     │                     └─────────────┘   │
                                     └───────────────────────────────────────┘
```

**Usage modes:**
- **Remote MCP (recommended)**: Point any MCP client to `https://addon-finder.eticco.es` — nothing to install
- **Local MCP (STDIO)**: The [PyPI package](https://pypi.org/project/ai-odoofinder-mcp/) runs locally against your own backend (self-hosting)

**Components:**
- **MCP Server** (Streamable HTTP): public endpoint for MCP clients
- **FastAPI Backend**: hybrid search engine (internal)
- **PostgreSQL + pgvector**: 19,700+ modules with embeddings

> **Public instance** hosted by [Eticco](https://www.eticco.es). Search over OCA community modules is **open, no login required**. Eticco is also extending the service with its own internal modules; that part requires authentication and is for internal use only.

---

## Statistics

| Metric | Value |
|--------|-------|
| Indexed Modules | **19,700+** |
| Odoo Versions | 8 (12.0 – 19.0) |
| With AI Enrichment | **100%** |

---

## Installation

**No installation needed.** AI-OdooFinder is available as a public remote MCP server:

```
https://addon-finder.eticco.es
```

| | |
|---|---|
| **Transport** | Streamable HTTP |
| **Authentication** | None for OCA community modules |
| **Tool** | `search_odoo_modules` |

Add that URL to your MCP client (see below). If your client only supports local STDIO servers, use the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge (requires Node.js):

```json
{
  "mcpServers": {
    "ai-odoofinder": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://addon-finder.eticco.es"]
    }
  }
}
```

### IDE/Client Configuration

<details>
<summary><b>Claude.ai Web / Claude Desktop</b></summary>

1. Go to **Settings** > **Connectors**
2. Click **"Add custom connector"**
3. Enter the MCP server URL:
   ```
   https://addon-finder.eticco.es
   ```
4. Save and start searching

> Custom connectors are shared between Claude.ai and Claude Desktop. On older Desktop versions without connectors, use the `mcp-remote` config above in `claude_desktop_config.json`.

</details>

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

```bash
claude mcp add --transport http ai-odoofinder https://addon-finder.eticco.es
```

Usage:
```bash
claude
> I need an Odoo 17 module for subscriptions
```

</details>

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

1. Go to **Settings** > **Apps & Connectors** > **Advanced** and enable **Developer Mode**
2. Create a new connector with URL `https://addon-finder.eticco.es`
3. Authentication: **None**

**Usage:**
```
Use ai-odoofinder to find Odoo 17 modules for inventory
```

</details>

<details>
<summary><b>VS Code (GitHub Copilot)</b></summary>

Create `.vscode/mcp.json` (project) or add it to your user `mcp.json`:

```json
{
  "servers": {
    "ai-odoofinder": {
      "type": "http",
      "url": "https://addon-finder.eticco.es"
    }
  }
}
```

> **For Business/Enterprise**: Admin must enable the "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": {
      "url": "https://addon-finder.eticco.es"
    }
  }
}
```

</details>

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

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "ai-odoofinder": {
      "serverUrl": "https://addon-finder.eticco.es"
    }
  }
}
```

</details>

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

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

```json
{
  "context_servers": {
    "ai-odoofinder": {
      "url": "https://addon-finder.eticco.es"
    }
  }
}
```

</details>

<details>
<summary><b>Antigravity and other STDIO-only clients</b></summary>

Use the `mcp-remote` bridge:

```json
{
  "mcpServers": {
    "ai-odoofinder": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://addon-finder.eticco.es"]
    }
  }
}
```

> **See full troubleshooting**: [MCP Client Configurations](docs/en/MCP_CLIENT_CONFIGURATIONS.md)

</details>

<details>
<summary><b>Local STDIO package (self-hosted backend)</b></summary>

The [`ai-odoofinder-mcp`](https://pypi.org/project/ai-odoofinder-mcp/) PyPI package runs the MCP server locally and talks to the FastAPI backend REST API. The public instance does not expose that REST API, so this mode is meant for **your own deployment** (see [Deployment & Operations](docs/en/DEPLOYMENT_OPERATIONS.md)):

```json
{
  "mcpServers": {
    "ai-odoofinder": {
      "command": "uvx",
      "args": ["ai-odoofinder-mcp"],
      "env": {
        "AI_ODOOFINDER_API_URL": "http://localhost:8989"
      }
    }
  }
}
```

> Requires [uv](https://docs.astral.sh/uv/).

</details>

**Full configuration guide**: [MCP Client Configurations](docs/en/MCP_CLIENT_CONFIGURATIONS.md)

---

## Client Compatibility Matrix

| Client | Remote URL | Via `mcp-remote` | Notes |
|--------|:---------:|:----------------:|-------|
| Claude.ai Web | ✅ | — | Custom connector |
| Claude Desktop | ✅ | ✅ | Connector or bridge |
| Claude Code CLI | ✅ | ✅ | `--transport http` |
| ChatGPT Dev Mode | ✅ | — | Developer Mode |
| VS Code Copilot | ✅ | ✅ | `type: http` |
| Cursor | ✅ | ✅ | |
| Windsurf | ✅ | ✅ | `serverUrl` |
| Zed | ✅ | ✅ | |
| Antigravity | ⚠️ | ✅ | Use the bridge |

**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

Once connected, simply ask in natural language:

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

Your assistant will call `search_odoo_modules` and show compatible OCA modules with their repository, summary and GitHub link.

Check the service status:

```bash
curl https://addon-finder.eticco.es/health
```

> The FastAPI REST API (`/search`, `/stats`) is only exposed in self-hosted deployments (`http://localhost:8989`).

---

## Tech Stack

| Component | Technology |
|-----------|------------|
| Backend | FastAPI (Python 3.14) |
| 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 | Eticco infrastructure (Docker + nginx) |

---

## 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.14+
- [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 Pérez 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