Odoo Index MCP

A lightweight MCP (Model Context Protocol) server for indexing Odoo code elements. Designed to help coding agents quickly look up models, fields, functions, views, and other Odoo components with their exact file locations.

Features

• Fast Indexing: Uses AST parsing for Python and lxml for XML

• Incremental Updates: Only re-indexes changed files (MD5 hash tracking)

• Comprehensive Coverage: Indexes models, fields, methods, views, menus, actions, access rights, rules, scheduled actions, report templates, controller routes, and more

• Multiple References: Tracks all occurrences (definition, inheritance, override, etc.)

• Lightweight: Pure SQLite, no vector DB, no embeddings

• MCP Compatible: Works with Claude Desktop and other MCP clients

What Gets Indexed

Core Elements

• Models: Name, type (regular/transient/abstract), inheritance

• Fields: Name, type, attributes (required, readonly, compute, related, etc.)

• Functions/Methods: Name, decorators (@api.depends, @api.onchange, etc.)

• Views: Type (form/tree/kanban/search), model, inheritance

• Menus: Hierarchy, actions, security groups

• Actions: Type (act_window/server/report), models, domains

• Access Rights: Model permissions by security group

• Record Rules: Domain-based access rules

• Controller Routes: HTTP/JSON routes with auth types

• Scheduled Actions: Cron jobs with intervals

• Report Templates: QWeb templates

• Module Metadata: Dependencies, version, description

Multiple References

Each element can have multiple file:line references:

• definition: Where it's originally defined

• inheritance: Where models are extended

• override: Where methods/fields are overridden

• reference: Where it's referenced

• modification: Where views are modified with xpath

Installation

Prerequisites

• Python 3.10+

• uv package manager

Setup

# Clone or navigate to the project
cd odoo-index-mcp

# Create .env file
cp .env.example .env

# Edit .env and set your ODOO_PATH
nano .env

# Install dependencies with uv
uv sync

Usage

CLI Tool

# Full indexing
uv run python cli.py --index

# Incremental indexing (skip unchanged files)
uv run python cli.py --index --incremental

# Index specific modules
uv run python cli.py --index --modules sale,account,stock

# Clear database and re-index
uv run python cli.py --clear --index

# Show statistics
uv run python cli.py --stats

# Search from CLI
uv run python cli.py --search "sale.order" --type model
uv run python cli.py --search "partner_id" --type field --module sale

# Search XML IDs
uv run python cli.py --search-xml-id "action_view_%"
uv run python cli.py --search-xml-id "action_view_sale_order" --module sale

MCP Server

# Start MCP server
uv run odoo-index-mcp

Claude Desktop Integration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "odoo-index": {
      "command": "uv",
      "args": ["run", "odoo-index-mcp"],
      "cwd": "/path/to/odoo-index-mcp",
      "env": {
        "ODOO_PATH": "/path/to/odoo"
      }
    }
  }
}

MCP Tools

The server provides 7 MCP tools:

1. search_odoo_index

Search for elements by name with wildcard support.

Parameters:

• query (str): Search term (supports SQL LIKE with %)

• item_type (str, optional): Filter by type

• module (str, optional): Filter by module

• parent_name (str, optional): Filter by parent (for fields/methods)

• limit (int, default=50): Max results

Example:

search_odoo_index(query="sale.order", item_type="model")
search_odoo_index(query="partner%", item_type="field", module="sale")

2. get_item_details

Get complete details for a specific element including related items.

Parameters:

• item_type (str): Type of item

• name (str): Item name

• parent_name (str, optional): Parent (for fields/methods)

• module (str, optional): Module to disambiguate

Example:

get_item_details(item_type="model", name="sale.order")
get_item_details(item_type="field", name="partner_id", parent_name="sale.order")

3. list_modules

List all indexed modules with item counts.

Parameters:

• pattern (str, optional): Filter by name pattern

Example:

list_modules()
list_modules(pattern="sale")

4. get_module_stats

Get detailed statistics for a module.

Parameters:

• module (str): Module name

Example:

get_module_stats(module="sale")

5. find_references

Find all references to an element across the codebase.

Parameters:

• item_type (str): Type of item

• name (str): Item name

• reference_type (str, optional): Filter by type (definition/inheritance/etc)

Example:

find_references(item_type="model", name="sale.order")
find_references(item_type="model", name="sale.order", reference_type="inheritance")

6. search_by_attribute

Advanced search by element attributes.

Parameters:

• item_type (str): Type to search

• attribute_filters (dict): Attribute filters

• module (str, optional): Filter by module

• limit (int, default=50): Max results

Example:

# Find all Many2one fields
search_by_attribute(
    item_type="field",
    attribute_filters={"field_type": "Many2one"}
)

# Find all transient models (wizards)
search_by_attribute(
    item_type="model",
    attribute_filters={"model_type": "transient"}
)

# Find all form views
search_by_attribute(
    item_type="view",
    attribute_filters={"view_type": "form"}
)

7. search_xml_id

Search for XML IDs by name pattern.

Parameters:

• query (str): Search term (supports SQL LIKE patterns with %)

• module (str, optional): Filter by module

• limit (int, default=50): Max results

Example:

# Find all action_view XML IDs
search_xml_id(query="action_view_%")

# Find specific action
search_xml_id(query="action_view_sale_order")

# Find form views in sale module
search_xml_id(query="%_form_view", module="sale")

Performance

• Indexing Speed: ~500-1000 files/second with concurrent processing and async database operations

• Database Size: ~50-100MB for typical Odoo installation

• Search Speed: <50ms for exact match, <200ms for pattern search

• Memory Usage: <500MB during indexing, <100MB when serving

• Database: Async connection pooling with aiosqlite for efficient concurrent writes

Configuration

Environment variables in .env:

# Required
ODOO_PATH=/path/to/odoo

# Optional (with defaults)
SQLITE_DB_PATH=./odoo_index.db
LOG_LEVEL=INFO
MAX_CONCURRENT_MODULES=4
MAX_CONCURRENT_FILES=8

Project Structure

odoo-index-mcp/
├── pyproject.toml              # uv project config
├── .env.example                # Environment template
├── .python-version             # Python version
├── README.md                   # This file
├── cli.py                      # CLI tool
├── odoo_index_mcp/
│   ├── __init__.py
│   ├── config.py               # Configuration
│   ├── database.py             # SQLite operations
│   ├── indexer.py              # Main indexing logic
│   ├── server.py               # FastMCP server
│   ├── tools.py                # MCP tool implementations
│   └── parsers/
│       ├── __init__.py
│       ├── python_parser.py    # AST parsing for Python
│       ├── xml_parser.py       # XML parsing for views/data
│       ├── csv_parser.py       # CSV parsing for access rights
│       └── manifest_parser.py  # Manifest file parsing

Database Schema

The index uses a normalized SQLite schema with 3 main tables:

1. indexed_items: Core item data (type, name, module, attributes JSON)

2. item_references: File locations (many-to-one with items)

3. file_metadata: File hashes for incremental indexing

All queries use proper indexes for fast lookups.

Development

# Install development dependencies
uv sync

# Run tests (TODO: add tests)
uv run pytest

# Format code
uv run black .

# Type checking
uv run mypy .

License

MIT

Contributing

Contributions welcome! Please:

1. Fork the repo

2. Create a feature branch

3. Add tests for new functionality

4. Submit a pull request

Support

For issues or questions:

• Open an issue on GitHub

• Check the documentation in ODOO_CODE_INDEXER.md

Roadmap

Future enhancements (not in v1):

• Call graph analysis

• Full-text search in method bodies

• Dependency graph visualization

• Watch mode (auto-reindex on changes)

• Web UI for browsing

• Export to other formats