# Odoo MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-1.0-green)](https://modelcontextprotocol.io/)

An MCP (Model Context Protocol) server for managing Odoo development environments with AI assistants.

## 🎯 Overview

This MCP server provides 19 tools to manage Odoo development environments, allowing AI assistants to:
- Control Odoo server (start, stop, restart, status)
- Manage modules (update, install, test)
- Switch between databases
- Navigate project directories
- View logs and configurations

Perfect for developers who want their AI assistants to remember and manage Odoo operations consistently across conversations.

## Architecture & the two surfaces

The management logic lives once, in `src/core.ts`, and is reached through two
thin entry points plus a Claude Code skill:

```
src/core.ts    All Odoo logic + smart output filtering (single source of truth)
src/index.ts   MCP server  → for Claude Desktop        (build/index.js)
src/cli.ts     odoo-cli    → for Claude Code / terminal (build/cli.js)
```

Skills and MCP reach your machine through different doors, so each Claude
surface uses the entry point that fits it:

| Surface | How it reaches local Odoo | What it uses |
|---|---|---|
| **Claude Desktop** | a local MCP process it launches | the **MCP server** (`build/index.js`) |
| **Claude Code** | host shell access | the **`odoo-manage` skill** → `odoo-cli` |

Why the split: a Claude Desktop skill runs sandboxed and cannot execute the
local CLI, so Desktop needs the MCP (a real local process) to touch your Odoo
install. Claude Code has host shell access, so a skill calling `odoo-cli` is the
lighter option there — the 19 MCP tool schemas don't have to sit in context.
Both paths run the same `core.ts`, including the identical output filtering.

The Claude Code skill lives at `~/.claude/skills/odoo-manage/SKILL.md` (it calls
`build/cli.js`, also installed as the `odoo` command). The orientation that
Desktop needs is carried by the MCP itself — the `odoo-help` prompt and the tool
descriptions — so no separate Desktop skill is required.

The **`stream`** capability — pull a remote nellika.sh / tcff Odoo database +
filestore (over SSH, `pg_dump | pg_restore` and `tar | tar`, in parallel, no temp
files) straight into the active local project — has a **single implementation**
(the `stream` verb in `manage_odoo.sh`) exposed three ways: the `odoo stream`
CLI command, the `odoo_project action=stream` MCP action, and a dedicated
**`odoo-stream`** Claude Code skill. The skill is vendored under `skill-stream/`
(rendered to `~/.claude/skills/odoo-stream/` by the installer) and is just a thin
wrapper that `exec`s the engine verb. Local Postgres major must be ≥ the remote's
(production is PG17).

The bash **engine** `manage_odoo.sh` is vendored at `scripts/manage_odoo.sh` and
installed as the `manage_odoo` command; `core.ts` invokes it by absolute path and
passes `ODOO_BASE` so it operates on the resolved base.

### Environment layout this manages

- **Base (fixed):** `~/odoo` — holds the active `odoo.conf` and one
  `odoo-<project>.conf` per project. (Legacy location `~/git/odoo18` is used as a
  fallback until the base is moved.)
- **Sources live inside the base, `_`-prefixed so they stand out from the
  unprefixed project addon symlinks:** `_odoo18/` (CE 18), `_enterprise18/`
  (EE 18), `_odoo19/` (CE 19), `_enterprise19/` (EE 19), plus `_venv18/`,
  `_venv19/`, and `_data/`.
- **18 vs 19 is per-project, not a separate tree.** The active `odoo.conf`
  selects it via its `; odoo_src` / `; python_venv` markers and `addons_path`.
  Switching project (`odoo_switch_database` / `odoo switch`) is what changes
  the running version — there is no version flag to set.

## Features

- **Server Control**: Start, stop, restart, and check status of Odoo server
- **Module Management**: Update, install, and manage Odoo modules
- **Frontend Updates**: Update frontend modules with automatic server restart
- **Testing**: Run Odoo tests with optional filtering
- **Database Management**: Switch between databases, list available databases
- **Backups & fresh DBs**: Import a backup (.zip/.sql/.dump) or reset to a fresh DB
- **Production sync (`stream`)**: Stream a remote nellika.sh/tcff Odoo db+filestore
  (over SSH, in parallel, no temp files) into the active local project
- **Logging**: Retrieve Odoo log entries

## Installation

### 1. Install Dependencies

```bash
cd ~/git/odoo-mcp-server
npm install
```

### 2. Configure Claude Desktop

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

```json
{
  "mcpServers": {
    "odoo": {
      "command": "node",
      "args": ["/Users/dgoo2308/git/odoo-mcp-server/build/index.js"]
    }
  }
}
```

### 3. Restart Claude Desktop

The Odoo management tools will now be available in Claude.

## Terminal commands (`odoo` / `manage_odoo`)

`npm run setup` (below) installs two commands into `~/.local/bin`:

- **`odoo`** — the smart front door (`build/cli.js`): same code as the skill/MCP,
  with output filtering and path helpers. **Use this.**
- **`manage_odoo`** — the raw bash engine (`scripts/manage_odoo.sh`): same verbs,
  unfiltered output. Operates on `$ODOO_BASE` (default `~/odoo`).

```bash
# examples
odoo status
odoo list
odoo switch verita
odoo update nell_thai_qr --error-only
odoo test purchase_dual_unit
odoo import ~/Downloads/backup.zip --neutralize   # drops+restores the active DB
odoo stream tcff_production_odoo --neutralize      # stream remote prod db+filestore into the active project
odoo logs --lines 200
```

Run `odoo help` for the full command list. Result text goes to stdout;
`[Executing]`/`[Success]` diagnostics go to stderr. Options: `--error-only`,
`--tags <tags>`, `--lines <n>`, `--base <path>` (default `~/odoo`, fallback
`~/git/odoo18`).

## Install everything (skill + commands)

`install.sh` installs all three pieces: the `odoo-manage` Claude Code skill, the
`odoo` command, and the `manage_odoo` command.

```bash
cd ~/git/odoo-mcp-server
npm run setup        # or: ./install.sh
```

The installer builds `build/cli.js` if needed, renders the skill with the
absolute path of *this* checkout (so it works no matter where the repo is
cloned), and symlinks `odoo` / `manage_odoo` into `~/.local/bin`. Re-run with
`--force` to overwrite an existing skill file (`./install.sh --force`). Env:
`ODOO_BIN_DIR` (default `~/.local/bin`), `CLAUDE_SKILLS_DIR` (default
`~/.claude/skills`). Start a new Claude Code session to pick up the skill.

To set this up on another computer:

```bash
git clone https://github.com/dannyg-sys/odoo-mcp-server.git ~/git/odoo-mcp-server
cd ~/git/odoo-mcp-server
npm install && npm run build
npm run setup
```

## Bootstrap a fresh Odoo base

`npm run setup` installs the *tooling*. To create the Odoo *base* itself on a new
machine (the `~/odoo` layout: clone CE 18/19 + Enterprise 18/19, build the
per-version venvs, seed `_data`/`_scripts`/`_concepts`, the docs, and a sample
config), run the environment bootstrap:

```bash
npm run setup-env        # or: ./scripts/setup_odoo_env.sh
```

Requires git, Python 3.10+, PostgreSQL, and **GitHub access to the private
`odoo/enterprise` repo** (SSH key or HTTPS token). Env vars: `ENTERPRISE_REMOTE=https`,
`SKIP_ENTERPRISE=1`, `FULL_CLONE=1`, `PYTHON=python3.11`, `ODOO_BASE=/path`.
Idempotent — re-running skips what already exists.

## Available Tools

The MCP exposes **four** tools, each taking an `action` (kept small so Claude
Desktop reliably loads them all):

- **`odoo_server`** — `action`: `start` | `stop` | `restart` | `status` | `shell`
- **`odoo_modules`** — `action`: `update` | `install` | `frontend` | `test`
  (`modules`, `testTags`, `errorOnly`); output is filtered to errors/warnings
- **`odoo_project`** — `action`: `list` | `switch` | `new` | `import` | `fresh` | `stream`
  (`project`, `name`, `odooVersion`, `enterprise`, `modules`, `repo`, `httpPort`,
  `backupFile`, `remoteHost`, `remoteDb`, `remoteDataDir`, `dbOnly`, `filestoreOnly`,
  `neutralize`, `noStart`). **Destructive**: `import`/`fresh`/`stream` drop the active DB;
  `new` creates the named DB.
- **`odoo_info`** — `action`: `logs` | `config-path` | `project-config` |
  `project-dir` | `addons-dir` | `enterprise-dir` (`project`, `lines`)

The `odoo-help` prompt documents the same. (The CLI / `odoo` command keeps the
full set of named subcommands — see "Terminal commands" above.)

## Usage Examples

```
"Start Odoo"
"Update the purchase_dual_unit module"
"Install stock_account and hr modules"
"Run tests for the sale module"
"Switch to the nellika database"
"Stream tcff production into my local project and neutralize it"
"Show me the last 100 log lines"
"Where is the project directory for hhfbs?"
"What's the path to the Odoo core addons?"
"Show me the enterprise directory"
```

## Configuration

### Choosing the Odoo version

You normally don't. The Odoo version (18 vs 19) is selected per project by the
active `odoo.conf` — switch project with `odoo_switch_database` (or
`odoo switch <project>`) and the version follows. See
[Environment layout](#environment-layout-this-manages).

### Using a different base directory

The base defaults to `~/odoo`, falling back to `~/git/odoo18`. To target a
different base, pass an absolute path: the MCP tools accept a `version` argument
and the CLI accepts `--base <path>`. The directory must look like an Odoo base
(have an `odoo.conf` or at least one `odoo-<project>.conf`).

```bash
odoo status --base /path/to/some/base
```

After changing source, rebuild:

```bash
npm run build
```

## Requirements

- Node.js 16+
- An Odoo base directory (`~/odoo`) with project configs; the `manage_odoo.sh`
  engine is installed by `npm run setup`
- Claude Desktop (MCP) and/or Claude Code (skill + `odoo` command)

## Development

```bash
# Build
npm run build

# Watch mode (auto-rebuild)
npm run watch
```

## Troubleshooting

### Server not found in Claude

1. Check Claude Desktop config file path
2. Ensure build directory exists: `ls ~/git/odoo-mcp-server/build/`
3. Restart Claude Desktop completely

### Commands failing

1. Check the base path exists: `ls ~/odoo` (or the legacy `~/git/odoo18`)
2. Verify the engine is installed: `command -v manage_odoo`
3. Check logs with `odoo logs` (or the `odoo_get_logs` MCP tool)

## License

MIT