Odoo Open Source Intelligence

Odoo Open Source Intelligence, or Odoo OSI, is an enterprise-grade platform for discovering, evaluating, comparing, and recommending open-source Odoo modules before teams write custom code.

The AI-facing interface is Odoo OSI MCP, an unofficial MCP server that lets coding agents search and inspect indexed OCA and trusted open-source Odoo repositories.

Odoo OSI is not affiliated with, endorsed by, or sponsored by the Odoo Community Association (OCA) or Odoo S.A. OCA and Odoo names are used only to identify public open-source repositories and ecosystem references.

Current Build Stage

This repository now has the first working backend and MCP vertical slice:

• FastAPI API for health, repositories, modules, search, code search, and solution finding
• PostgreSQL schema and Alembic migration for repositories, branches, modules, dependencies, source files, and symbols
• GitHub/OCA ingestion for repositories, Odoo version branches, manifests, metadata, dependencies, and selected source files
• Odoo-aware Python, XML, CSV security, and README extraction
• requirement-to-module search with version, license, manifest, and indexed document signals
• source-backed recommendation evidence
• cross-version recommendation candidates with migration/backport guidance
• live GitHub/OCA fallback for likely modules that are not indexed yet
• MCP server with search, solution, code, module, and dependency tools
• persisted indexing job ledger surfaced through /indexing/status
• local PostgreSQL and Redis configuration
• linting and test coverage

Quick Start

Follow these steps to run Odoo OSI locally from a fresh clone.

1. Prerequisites

Install:

• Python 3.11 or newer
• Docker and Docker Compose
• Git
• A GitHub personal access token for practical indexing and fallback search

2. Clone The Repository

git clone https://github.com/krishnakantjoshi/odoo-osi-mcp.git
cd odoo-osi-mcp

3. Create Local Configuration

cp .env.example .env

Open .env and set your own GitHub token:

ODOO_OSI_GITHUB_TOKEN=YOUR_GITHUB_TOKEN

.env is ignored by git. Do not commit real tokens.

4. Start PostgreSQL And Redis

docker compose up -d postgres redis

5. Create A Python Environment

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,mcp]"

On Windows PowerShell, activate the virtual environment with:

.\.venv\Scripts\Activate.ps1

6. Run Database Migrations

alembic upgrade head

7. Start The API Server

uvicorn odoo_osi.api.app:create_app --factory --reload

Check the API:

curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/indexing/status

8. Discover And Index A Small Sample

In another terminal, activate the virtual environment again:

source .venv/bin/activate

Discover module manifests from one OCA repository:

odoo-osi discover-oca \
  --repository purchase-workflow \
  --odoo-version 18.0 \
  --branch-limit 1 \
  --module-limit 20 \
  --persist

Index source evidence for a small set of modules:

odoo-osi index-source \
  --repository purchase-workflow \
  --odoo-version 18.0 \
  --module-limit 10 \
  --file-limit 30

Check coverage:

odoo-osi coverage
curl http://127.0.0.1:8000/indexing/coverage

9. Search For Modules

curl -X POST http://127.0.0.1:8000/solutions/find \
  -H "Content-Type: application/json" \
  -d '{"requirement":"multi level purchase approval","odoo_version":"18.0","limit":5}'

10. Run The MCP Server

For a local MCP client, use stdio:

odoo-osi run-mcp

Most MCP clients use a config like this:

{
  "mcpServers": {
    "odoo-osi": {
      "command": "/absolute/path/to/odoo-osi-mcp/.venv/bin/odoo-osi",
      "args": ["run-mcp"],
      "cwd": "/absolute/path/to/odoo-osi-mcp",
      "env": {
        "ODOO_OSI_GITHUB_TOKEN": "REPLACE_WITH_YOUR_OWN_GITHUB_TOKEN"
      }
    }
  }
}

The same example is in mcp.json.example. If your MCP client does not support env, put the token in your local .env instead.

11. Run Tests

python -m ruff check .
python -m pytest

Example Prompts

After configuring the MCP server in your AI coding tool, try these prompts.

Check Index Coverage

Use the odoo-osi MCP server.

Before searching for modules, call get_coverage_report and summarize:
1. how many modules are indexed
2. how many modules have source evidence
3. whether results should be treated as complete or partial
4. what indexing step I should run next

Find An Existing Module Before Custom Development

Use the odoo-osi MCP server.

I am developing on Odoo 18 Community.

Requirement:
I need a multi-level purchase approval workflow.

Before writing custom code, check whether an existing open-source Odoo/OCA module satisfies
this requirement.

Return exact-version matches first, then older-version migration candidates, then discovered
but not indexed candidates. Include module name, repository, license warning, evidence level,
version status, migration effort, source evidence, README evidence, security-rule evidence,
and indexing guidance.

Do not generate custom code until I review the MCP result.

Inspect A Candidate Module

Use the odoo-osi MCP server.

Inspect the module purchase_request from OCA/purchase-workflow for Odoo 18.0.

Summarize:
1. manifest metadata
2. dependencies
3. license warnings
4. models and inherited models
5. views, actions, and menus
6. security access rules
7. README evidence
8. whether it is safe to use as implementation reference

Search For A Code Pattern

Use the odoo-osi MCP server.

Search indexed OCA source for modules that extend purchase.order in Odoo 18.0.

Return the repository, module, file path, symbol type, model name, inherited model, and any
useful XML IDs.

Prepare A Development Brief

Use the odoo-osi MCP result as the primary reference.

Target:
- Odoo version: 18.0
- Edition: Community
- Organization/developer: Your Org
- Technical module prefix: your_org
- New module technical name: your_org_purchase_approval

Produce a development brief, branding brief, exact file plan, and minimal test plan.
Do not write code until the brief and file plan are approved.

For full prompt templates, see AI Development Brief Guide.

Troubleshooting

• Database connection fails: run docker compose up -d postgres redis, then rerun alembic upgrade head.
• GitHub rate limits: set ODOO_OSI_GITHUB_TOKEN in .env.
• MCP client cannot find odoo-osi: use the absolute path to .venv/bin/odoo-osi in your MCP config.
• Search returns few results: run discovery and source indexing first. A fresh database has no indexed modules.

Local Credentials

There are two different GitHub credentials you may use:

• GitHub personal access token: used by Odoo OSI to call the GitHub API for indexing and fallback search.
• SSH key: used by git itself when you push or pull repositories over SSH.

GitHub API Token

Create a fine-grained personal access token in GitHub:

1. Open GitHub.
2. Go to Settings.
3. Open Developer settings.
4. Open Personal access tokens.
5. Choose Fine-grained tokens.
6. Generate a new token.
7. Use the minimum access needed. For public OCA indexing, read-only public repository access is enough.

Put that token in your local .env file:

ODOO_OSI_GITHUB_TOKEN=YOUR_GITHUB_TOKEN

.env is ignored by git. If your MCP client uses a private mcp.json, that file is ignored too. Do not put real tokens in mcp.json.example, docs, tests, or committed source.

GitHub docs:

• Managing personal access tokens

Git SSH Key

For git push/pull access over SSH, keep your SSH key outside the repo, usually in ~/.ssh, and add the public key to your Git hosting provider.

On macOS/Linux:

ssh-keygen -t ed25519 -C "your_email@example.com"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
cat ~/.ssh/id_ed25519.pub

Copy the public key output and add it in GitHub under Settings > SSH and GPG keys > New SSH key. Never copy or commit the private key file.

GitHub docs:

• Generating a new SSH key and adding it to the ssh-agent

API Endpoints

The health endpoint:

GET /health

Key working endpoints:

GET /repositories
GET /modules
POST /search
POST /search/code
POST /solutions/find

Roadmap

See ROADMAP.md.

Ingestion

See docs/ingestion.md for GitHub token setup and indexing commands.

MCP

See docs/mcp.md for the Odoo OSI MCP server commands and tools.

Project Status And Notices

• This project is unofficial; see NOTICE.md.
• Contributions are welcome; see CONTRIBUTING.md.
• Security reporting and credential guidance are in SECURITY.md.
• Privacy and hosted deployment notes are in PRIVACY.md.