mcp-odoo-shell: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an MCP (Model Context Protocol) server that provides access to an Odoo shell environment. The server acts as a bridge between MCP clients and Odoo, allowing execution of Python code within an Odoo database context.

Architecture

The project is organized as a Python package in src/mcp_odoo_shell/:

• shell_manager.py: OdooShellManager class for managing persistent Odoo shell subprocess with threaded I/O
• server.py: MCP server setup and global state management
• tools.py: MCP tool functions that provide the main functionality:
  • execute_odoo_code: Execute arbitrary Python code in Odoo shell context
  • reset_odoo_shell: Restart the shell process to clear state
  • list_odoo_models: Query available Odoo models
  • odoo_model_info: Get detailed information about specific models
• main.py: Entry point for running the MCP server
• __init__.py: Package exports and public API

Key Configuration

The server requires these environment variables:

• ODOO_BIN_PATH: Path to odoo-bin executable (defaults to /usr/bin/odoo-bin)
• ODOO_ADDONS_PATH: Comma-separated addon directories (defaults to /odoo/addons)
• ODOO_DATABASE: Database name (defaults to 'odoo')
• ODOO_CONFIG_FILE: Optional Odoo configuration file path

Development Commands

Install dependencies:

uv sync --dev

Run the server:

uv run odoo-shell-mcp
# or
uv run python -m mcp_odoo_shell.main

Run tests:

PYTHONPATH=src uv run pytest
# or with coverage
PYTHONPATH=src uv run pytest --cov=mcp_odoo_shell --cov-report=term-missing

Linting and formatting:

uv run ruff check .          # Check code
uv run ruff check --fix .    # Fix issues
uv run ruff format .         # Format code

Build package:

uv build

Python dependencies management: This project uses uv for dependency management and hatch for minimal build system. Dependencies are defined in pyproject.toml [project] section.