Brass-Monkey 🐒: Gemini CLI Extension for Odoo

Status: ✅ Stable
Verified Compatibility: Odoo v15 through v18+ (Enterprise and Community).

Brass-Monkey is a high-fidelity, secure, and cognitively optimized Gemini CLI extension and Model Context Protocol (MCP) bridge for Odoo. It enables AI agents to navigate Odoo's complex ERP/CRM architecture, manage multiple instances, and perform highly audited record operations with extreme context-window efficiency.

🌟 Key Features

The "Breadth vs. Depth" Search Paradigm: Uses lightweight paginated searches (search_records) for record discovery, and structured detail-fetchers (get_record / get_records) to build 360-degree interactive "Record Dashboards" containing child rows, Chatter threads, and real-time security ACLs.
In-Memory Metadata Caching: Accelerates default database queries to 0ms metadata latency by caching model configurations locally and performing parallel, background warming of parent-model schemas.
Hierarchical "Local Neighborhood" Navigation: Exposes Odoo's menus (get_menu) as pruned, recursive JSON trees that cleanly map ancestral breadcrumbs, direct children, and immediate folder siblings while pruning out 95% of unrelated system noise.
Self-Healing Action Resolution: Dynamically inspects Odoo's base tables to auto-resolve action types (get_action), supporting window, server, client, and report actions natively with zero parameter crashes.
Layered Credential Security: API keys are supplied by your host's env-var secret mechanism, or persisted to an AES-256-GCM encrypted local file; when the OS keychain (Windows Credential Vault, macOS Keychain, libsecret) is available it is used automatically as an enhancement.
Audit & Reversibility: Every write operation captures a "Before Snapshot" and logs a mandatory justification to Odoo's ir.logging and the record's Chatter.
30 Domain Skills: Deep functional expertise pre-loaded for Sales, MRP, Finance, HR, and more.

🚀 Quick Start

Brass-Monkey is one stdio MCP server (node dist/bundle/index.js) consumed by four surfaces through four thin manifests. Pick the row that matches how your agent runs — every surface launches the identical server, with no forked logic per platform.

Surface	Install	Config	Skills
Gemini CLI	`gemini extensions install …` (§1)	interactive prompts	✅ 30
Claude Code	`/plugin install brass-monkey@odoo-actinon` (§3)	install prompts → `ODOO_*`	✅ 30
Claude Desktop	install `brass-monkey.mcpb` (§4)	install dialog → `ODOO_*`	✗ tools only
Antigravity / generic MCP	standard `mcpServers` config (§6)	`env` block or `setup_instance`	✗ tools only

The 30 domain skills ride with the Gemini extension and the Claude Code plugin (both carry a skills/ manifest); the .mcpb and raw MCP-config paths deliver the tools only (see §4 note).

1. Installation

The recommended way to install Brass-Monkey is using the official Gemini CLI extension command. This will guide you through the interactive setup of your first Odoo instance.

gemini extensions install https://github.com/actinon-com/brass-monkey.git

2. Configuration

During installation, you will be prompted for:

Odoo Instance URL: e.g., https://my-company.odoo.com
Database Name: The name of your Odoo database.
Username / Email: Your login credentials.
API Key / Password: Your Odoo External API Key (recommended).

You can update these settings later or add additional instances using:

# Update existing default instance
gemini extensions config brass-monkey

Upgrade to a newer release with:

gemini extensions update brass-monkey

3. Install on Claude Code (plugin + marketplace)

Brass-Monkey is a self-serve Claude Code plugin. Add the marketplace, then install:

/plugin marketplace add actinon-com/brass-monkey
/plugin install brass-monkey@odoo-actinon

On install, Claude Code prompts for your Odoo URL, database, username, and API key (the key is stored via Claude Code's secure storage). These are injected into the server automatically — no further setup needed. Leave them blank to skip straight to the setup_instance tool instead (see Path B below).

Upgrade to a new release with:

/plugin update brass-monkey@odoo-actinon

Skills are namespaced under the plugin, e.g. /brass-monkey:odoo-sales.

4. Install on Claude Desktop (`.mcpb` bundle)

For non-CLI users, Brass-Monkey also ships as a one-click Claude Desktop bundle (.mcpb, the successor to the .dxt format).

Download brass-monkey.mcpb from the latest release.
Install it — double-click, drag it into the Claude Desktop window, or Settings → Extensions → Advanced settings → Install Extension….
In the install dialog, fill your Odoo URL, database, username, and API key (the key is masked and stored in your OS secure storage). Leave the fields blank to configure later via the setup_instance tool.

Upgrade by installing a newer .mcpb over the old one.

Note — skills: the .mcpb bundle delivers the Odoo MCP tools only. The 30 domain skills are a Claude Code feature and ship with the plugin (section 3), not the desktop bundle. For the full tools-plus-skills experience, use Claude Code.

5. Configuration on Claude Code / generic MCP hosts

The server is host-agnostic: it never depends on Gemini's interactive prompts. Any MCP host can configure it through either of two independent paths. (On the Claude Code plugin and Claude Desktop bundle above, Path A is wired to the install-time prompts for you.)

Path A — host-injected environment variables. Set the ODOO_* variables in your host's server entry; on startup they populate a single default instance (no tool call needed). This is the env-var contract:

Variable	Required	Description
`ODOO_ALIAS`	No (default `default`)	Alias for the injected instance.
`ODOO_URL`	Yes	Base URL, e.g. `https://my-company.odoo.com`.
`ODOO_DB`	Yes	Odoo database name.
`ODOO_USERNAME`	Yes	Login username or email.
`ODOO_API_KEY`	Yes	Odoo External API Key (recommended) or password. Sensitive — inject via your host's secret mechanism; never commit it.

ODOO_URL, ODOO_DB, and ODOO_USERNAME must all be present for the instance to register; ODOO_API_KEY is resolved for the instance named by ODOO_ALIAS.

Path B — the setup_instance tool (first-run). With no env vars set, call setup_instance from the client. It validates the credentials against Odoo, stores the API key (see Credential storage below), and persists non-secret metadata. Use it to add further instances alongside an env-injected default, too.

Both paths work with no Gemini-specific step. The mcp_config.json template (§6) plus the ODOO_* variables is all a raw MCP host needs.

6. Install on Antigravity / other MCP hosts (standard config)

Any host that reads a standard MCP mcpServers config — Antigravity, or the claude mcp add fallback — launches the very same server. In Antigravity, open the … menu in the agent panel → Manage MCP Servers → View raw config (the raw file lives under ~/.gemini/, e.g. ~/.gemini/config/mcp_config.json; on Windows ~/.gemini/antigravity/mcp_config.json). Add:

{
  "mcpServers": {
    "brass-monkey-odoo": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/brass-monkey/dist/bundle/index.js"],
      "env": {
        "ODOO_URL": "https://my-company.odoo.com",
        "ODOO_DB": "my-database",
        "ODOO_USERNAME": "me@company.com",
        "ODOO_API_KEY": "your-odoo-api-key"
      }
    }
  }
}

Use an absolute path in args rather than relying on cwd. The env block is Path A (§5) — it populates a default instance on startup. Omit env entirely to configure later via the setup_instance tool (Path B). The repo-root mcp_config.json is the same template in cwd + relative-args form, for hosts that honor cwd.

Prefer the CLI? Claude Code (and any host with an equivalent) can add it in one line:

claude mcp add brass-monkey-odoo \
  -e ODOO_URL=https://my-company.odoo.com \
  -e ODOO_DB=my-database \
  -e ODOO_USERNAME=me@company.com \
  -e ODOO_API_KEY=your-odoo-api-key \
  -- node /ABSOLUTE/PATH/TO/brass-monkey/dist/bundle/index.js

⬆️ Upgrading

Each surface upgrades independently, all to the same server version:

Platform	Upgrade command
Gemini CLI	`gemini extensions update brass-monkey`
Claude Code	`/plugin update brass-monkey@odoo-actinon`
Claude Desktop	Download the newer `brass-monkey.mcpb` from the latest release and install it over the old one.
Antigravity / generic	`git pull` your checkout, then `npm run build` to refresh `dist/bundle`.

🛠️ Available Tools

Category	Tool	Description
Discovery	`list_models`	Search and list Odoo's technical models with pagination.
	`inspect_model`	Perform a deep architectural audit of any Odoo model's fields, modules, and rules.
	`get_environment`	"World Map" orientation — server, user, company, and app context. Recommended first call in a session.
UX & Navigation	`get_menu`	Retrieve recursive, pruned JSON trees of menus (hierarchical drilling or semantic search).
	`get_action`	Retrieve Window, Server, Client, or Report Action details with view-mode bindings.
	`get_view`	Retrieve raw XML/definitions for Odoo form, tree, or kanban views.
	`trace_ui_path`	Discover exactly how to reach a model through the UI (Menus → Actions → Views).
Safe CRUD	`search_records`	Search Odoo records, returning a lightweight breadcrumbs-envelope and list totals.
	`get_record`	Retrieve a 360-degree detailed dashboard of a single record, including lines and chatter.
	`get_records`	Retrieve deep, multi-line detailed reports for multiple records in batch.
	`create_record`	Create new records in a specified model with mandatory business justification.
	`write_record`	Update existing records with field-level snapshot tracking.
	`unlink_record`	Delete records from Odoo (highly audited).
	`aggregate_records`	Server-side grouping and pivot-style aggregations with custom offset pagination.
Reports	`list_reports`	List all available PDF reports (Invoices, Quotations, Packing Slips) for a model.
	`download_report`	Generate and retrieve PDF report data.
	`download_file`	Download any file or attachment from an Odoo database to the local workspace.
Workspace	`setup_instance`	Add and authenticate new Odoo environments.
	`list_instances`	List all configured environments.
	`switch_instance`	Change the active environment.
	`remove_instance`	Delete an instance configuration and its stored credentials.
	`get_info`	Retrieve server version and configuration stats.
	`get_audit_log`	Retrieve recent local audit log entries for transparency.

💼 Domain Skills Catalog

Brass-Monkey includes specialized guidance for the following Odoo areas:

Foundation: relations (Partners), products, inventory, security.
Sales: crm, sales, purchasing, website, helpdesk.
Industrial: mrp (Manufacturing), plm (Engineering).
Projects: projects, timesheets, field-service.
Internal Ops: finance, hr, attendance, frontdesk.
Content: knowledge, documents, worksheets.
Intelligence: spreadsheets, dashboards.

💻 Local Development & Isolated Testing

For developers working on this extension, you can run isolated tests against your live Odoo database without modifying your stable global installation.

Create a local .env file in the root of the workspace (ignored by git):

ODOO_URL="https://my-company.odoo.com"
ODOO_DB="my-database"
ODOO_USERNAME="my-email@company.com"
ODOO_API_KEY="my-api-key"

Start the parallel MCP Inspectors using the helper script:

# Start all three inspectors (Production, Development, Python)
./start-inspectors.sh --all

# Start ONLY your local workspace development inspector (Port 6275, Proxy 6278)
./start-inspectors.sh --dev

Manual / standard MCP config: the repo-root mcp_config.json is a template for hosts that consume a raw MCP server entry. For installing Brass-Monkey on Antigravity or via claude mcp add, see §6 above. Replace the /ABSOLUTE/PATH/TO/brass-monkey placeholder with the absolute path to your checkout. All hosts launch the same node dist/bundle/index.js.

🛡️ Security & Privacy

Zero Cleartext Policy: API keys are never stored in your project folder or logged to the console.
Audit Trail: All AI actions are attributed and logged within Odoo's ir.logging and record Chatter.
Production Guard: Writing to Odoo requires an explicit business justification.

Credential storage

Keys are resolved in this order: OS keychain → encrypted local file → environment variable.

Environment variable (ODOO_API_KEY) — the primary path for Claude Desktop / Claude Code and any host that manages secrets for you. Nothing is written to disk.
Encrypted local file — the guaranteed cross-platform baseline for the setup_instance path, at ~/.gemini/brass-monkey/credentials.json (mode 0600). Values are encrypted with AES-256-GCM using a key derived from the current OS user and machine. This is obfuscation-grade: it protects against casual disk reads, backups, and file sync, but not against an attacker already running as your user (who can re-derive the same key). Legacy plaintext files from older versions are read transparently and re-encrypted on the next save.
OS keychain (Windows Credential Vault, macOS Keychain, Linux libsecret) — used automatically as a best-effort enhancement when the native keytar module loads. Because keytar is a native binary that cannot be shipped for every OS in a single bundle, it is treated as optional; the encrypted file above is the reliable baseline.

Set BRASS_MONKEY_NO_KEYCHAIN=1 to skip the native keychain and force the pure-JS encrypted-file path (useful on headless CI or in sandboxes).

📄 License

This project is licensed under the MIT License.

Name		Name	Last commit message	Last commit date
Latest commit History 131 Commits
.claude-plugin		.claude-plugin
.github		.github
dist		dist
docs		docs
scripts		scripts
skills		skills
src		src
tests		tests
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
GEMINI.md		GEMINI.md
LICENSE		LICENSE
README.md		README.md
gemini-extension.json		gemini-extension.json
manifest.json		manifest.json
mcp_config.json		mcp_config.json
package-lock.json		package-lock.json
package.json		package.json
start-inspectors.sh		start-inspectors.sh
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Brass-Monkey 🐒: Gemini CLI Extension for Odoo

🌟 Key Features

🚀 Quick Start

1. Installation

2. Configuration

3. Install on Claude Code (plugin + marketplace)

4. Install on Claude Desktop (`.mcpb` bundle)

5. Configuration on Claude Code / generic MCP hosts

6. Install on Antigravity / other MCP hosts (standard config)

⬆️ Upgrading

🛠️ Available Tools

💼 Domain Skills Catalog

💻 Local Development & Isolated Testing

🛡️ Security & Privacy

Credential storage

📄 License

About

Uh oh!

Releases 2

Packages

Uh oh!

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Brass-Monkey 🐒: Gemini CLI Extension for Odoo

🌟 Key Features

🚀 Quick Start

1. Installation

2. Configuration

3. Install on Claude Code (plugin + marketplace)

4. Install on Claude Desktop (.mcpb bundle)

5. Configuration on Claude Code / generic MCP hosts

6. Install on Antigravity / other MCP hosts (standard config)

⬆️ Upgrading

🛠️ Available Tools

💼 Domain Skills Catalog

💻 Local Development & Isolated Testing

🛡️ Security & Privacy

Credential storage

📄 License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

4. Install on Claude Desktop (`.mcpb` bundle)

Packages