odools-mcp

Give your AI coding assistant Odoo-aware code navigation through the official, unmodified Odoo Language Server (OdooLS). odools-mcp is a local, read-only MCP adapter: your assistant asks about source code; OdooLS resolves the supported relationships.

For example, an assistant can follow an Odoo model reference to its definition, find callers of an inherited method, inspect Python/XML/JavaScript hover information, and observe diagnostics while you edit an addon. The 0.3.0 tool contract also includes known-name symbol lookup and file outlines.

This analyzes files, not a running Odoo database. It does not install addons, inspect your registry or effective views, apply edits, or execute suggested commands. You do not need a running Odoo server, PostgreSQL or Docker for source analysis.

Choose your version first

Do not mix adapter and runtime versions:

Both version pairs use exact TypeScript/tsserver 6.0.2 for supported frontend analysis. The release target is 0.3.0: check GitHub Releases for actual asset availability. A tag, source checkout or build is not proof of publication. There is no npm registry distribution; the package remains private: true. Historical local 0.1.0 packages are not the recommended starting point.

Related MCP server: symbiont

Before you start

You need:

• Linux x64, or a Linux x64 WSL environment. Other managed-runtime platforms are not currently supported.

• Node.js 20 or newer. npm is needed only for source development, not the self-contained release bundle.

• An executable Python interpreter appropriate for your Odoo source checkout. Use an absolute path, such as your development virtualenv's bin/python.

• A local Odoo source tree, including odoo-bin and odoo/addons/base, and any custom/OCA addon repositories you want to analyze. A custom-addon-only repository is not a complete Odoo workspace. Source and Python must be visible to the adapter process: a host-launched adapter cannot use container-only paths.

• An MCP-capable coding client: OpenCode V2, Claude Code, or OpenAI Codex CLI.

• Network access for the initial release/runtime downloads. Runtime installation verifies pinned assets; ordinary serve never downloads or installs them.

Check your tools before continuing:

node --version
/absolute/path/to/your/venv/bin/python --version

Use a trusted development checkout. This is not a sandbox for hostile source, configuration or local users; see SECURITY.md.

Quick start: release 0.3.0

These commands consistently use adapter 0.3.0 + OdooLS 1.6.2. Use this route only when the matching assets are available on GitHub Releases; during release preparation, use the source route instead. Neither these instructions nor a local build attest that publication has occurred.

1. Download and verify the adapter

After confirming availability, download these two assets from the trusted v0.3.0 release:

• pyming-odools-mcp-0.3.0-linux-x64-bundle.tar.gz

• pyming-odools-mcp-0.3.0-linux-x64-bundle.tar.gz.sha256

From the download directory:

sha256sum -c pyming-odools-mcp-0.3.0-linux-x64-bundle.tar.gz.sha256 &&
  mkdir -p "$HOME/.local/share/odools-mcp/releases" &&
  mkdir "$HOME/.local/share/odools-mcp/releases/0.3.0-manual" &&
  tar -xzf pyming-odools-mcp-0.3.0-linux-x64-bundle.tar.gz \
    -C "$HOME/.local/share/odools-mcp/releases/0.3.0-manual"

NODE_BIN="$(command -v node)"
ADAPTER_CLI="$HOME/.local/share/odools-mcp/releases/0.3.0-manual/node_modules/@pyming/odools-mcp/dist/cli.js"
"$NODE_BIN" "$ADAPTER_CLI" --version --json

Require successful checksum verification before extraction. Do not extract over an existing installation; mkdir deliberately fails if that version directory already exists. A checksum detects changes against the checksum you obtained, so obtain both files through a trusted release channel.

The bundle contains compiled adapter code and production dependencies—not Node, OdooLS or the separate managed TypeScript runtime. PROVENANCE.json records the source, lock and runtime pins; FILES.json inventories the regular payload files except itself. The outer archive checksum is separate.

Extraction does not add odools-mcp to PATH. Keep using the selected Node executable and absolute CLI path. No npm install, build or npm link is needed.

2. Install and verify the matching runtime

In the same shell, with the variables above still set:

RUNTIME_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/odools-mcp/runtime-1.6.2"
"$NODE_BIN" "$ADAPTER_CLI" install-runtime \
  --version 1.6.2 --runtime-dir "$RUNTIME_DIR"
"$NODE_BIN" "$ADAPTER_CLI" verify-runtime --runtime-dir "$RUNTIME_DIR"

Both commands emit JSON. Installation downloads the exact pinned OdooLS, typeshed and TypeScript assets, verifies them and records an installed inventory. Invalid existing runtimes are refused, not silently repaired or overwritten. The runtime is separate from the adapter. Managed runtimeDir and discovery configurations verify its inventory when serving. Explicit-binary mode checks the selected backend version rather than that complete inventory; run verify-runtime separately before using an installed runtime through explicit-binary mode.

3. Choose your workspace and Python

Discovery recognizes conventional core, sibling-addon and Doodba layouts:

# Core plus sibling addon repositories
work/
  odoo/                  # contains odoo-bin and odoo/addons/base
  my-addons/
  OCA-repository/

# Doodba: use the resolved source root, not only private/
project/odoo/custom/src/
  odoo/
  private/
  OCA-repository/

Select the source root that contains the intended core and addon repositories. Discovery does not need to run Docker. If multiple cores or ambiguous addon layouts exist, use explicit configuration instead of guessing.

4. Connect your coding client

Start with this command array, replacing every placeholder with an absolute path. Client JSON does not expand shell variables such as $HOME, $ADAPTER_CLI or ~:

[
  "/absolute/path/to/node",
  "/absolute/path/to/user-root/.local/share/odools-mcp/releases/0.3.0-manual/node_modules/@pyming/odools-mcp/dist/cli.js",
  "serve",
  "--discover-workspace",
  "--workspace", "/absolute/path/to/work",
  "--python", "/absolute/path/to/your/venv/bin/python"
]

Use this array in client setup below. The explicit workspace makes this first setup independent of the directory from which your client launches MCP. For project-local clients, omitting --workspace discovers from the client's working directory. Omitting --python searches executable candidates on PATH, which may not be your Odoo interpreter.

serve is a stdio protocol process, not a web server or an interactive shell. It stays running for the client; diagnostic messages go to stderr, not protocol stdout.

5. Check the connection and try navigation

1. Reconnect the MCP in your client and inspect its advertised tool catalog. Adapter 0.3.0 has status, definition, declaration, references, hover, file_diagnostics, workspace_symbols and document_symbols.

2. Ask for status. dormant is healthy: the adapter is connected but has not started the heavier language server. Status does not activate it.

3. Start with workspace_symbols for a known model/method name, or exact search for a real Python reference or XML ID. Read the returned source, determine the exact line/column and call definition. Use document_symbols for a file outline. Input paths are workspace-relative; line and column are one-based Unicode code points.

4. Read the returned source to confirm the target. Subsequent calls reuse the backend.

Example tool input—replace the path and position with an actual reference:

{"path": "my-addons/my_module/models/sale_order.py", "line": 12, "column": 18}

Known-name lookup observes loaded analysis state, not exhaustive discovery. If loading or unavailable, use exact search/read to establish a navigation anchor.

Source development: 0.3.0

This route builds this source tree with the same 0.3.0 / 1.6.2 version pair. A source build is not a published/attested installation. Review the checkout/revision you build; a branch name alone is not provenance. Keep any working legacy 0.2.0 / 1.6.1 installation separate rather than overwriting it.

git clone https://github.com/extrememicro/odools-mcp.git
cd odools-mcp
npm ci
npm run build
NODE_BIN="$(command -v node)"
ADAPTER_CLI="$PWD/dist/cli.js"
"$NODE_BIN" "$ADAPTER_CLI" --version --json

Check the reported version before continuing. Only if this checkout reports 0.3.0 and declares OdooLS 1.6.2 should you run the following commands. If the public default branch does not yet contain that version, select a reviewed 0.3.0 revision before building. A legacy 0.2.0 checkout instead requires its own 1.6.1 runtime; do not apply the commands below to it.

RUNTIME_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/odools-mcp/runtime-1.6.2"
"$NODE_BIN" "$ADAPTER_CLI" install-runtime \
  --version 1.6.2 --runtime-dir "$RUNTIME_DIR"
"$NODE_BIN" "$ADAPTER_CLI" verify-runtime --runtime-dir "$RUNTIME_DIR"

Connect the client with your absolute checkout dist/cli.js path, rather than the 0.3.0 release-bundle path. Keep each adapter with its own verified runtime. For a fully qualified source entry point, the form is node /absolute/path/to/odools-mcp/dist/cli.js --version --json. Installing a global odools-mcp wrapper is optional; do not assume one exists.

See CONTRIBUTING.md for development checks, reproducible candidate packaging and native acceptance. The npm archive pyming-odools-mcp-0.3.0.tgz is a packaging artifact, not the recommended self-contained installation; no npm registry publication is claimed.

Tool reference and supported behavior

The eight 0.3.0 tools are read-only. Completion/resolve is not exposed, even if backend capabilities advertise it; no generic LSP passthrough, edit or command-execution tool is provided. Always inspect the live catalog: a running client can retain an older adapter until reconnect.

MCP clients qualify names differently. With server odools, OpenCode uses odools_<leaf> and Code Mode uses tools.odools.<leaf>; for example, odools_workspace_symbols / tools.odools.workspace_symbols. Raw leaves above are authoritative. Explicit-binary mode must use the selected adapter's exact OdooLS version, not an arbitrary language-server executable.

Positions and returned locations

• Position inputs: workspace-relative path, positive one-based line and column; columns count Unicode code points, not UTF-8 bytes or UTF-16 units.

• Semantic returned ranges: one-based code-point positions, with rooted paths constrained to configured roots. No arbitrary external file navigation is allowed.

• Diagnostic ranges: zero-based lines and UTF-16 character offsets. Do not reuse them directly as semantic tool inputs without conversion.

• Truncated or capped references are incomplete, not an exhaustive impact analysis.

Hover

Adapter 0.3.0 accepts lowercase .py, .xml and .js; legacy 0.2.0 accepts Python/XML. TypeScript hover is explicitly unsupported before activation, file open or RPC, while TypeScript document outlines remain supported. JS needs available JavaScript readiness; disabled/pending support is not a proven symbol miss.

Content is capped at 16,384 UTF-16 units, with surrogate-safe truncation. Ranges may be null when the backend supplies none; they are never fabricated. Changed source snapshots/backend generations require retry. Returned documentation is untrusted source data, not instructions; it triggers no link fetching or execution.

Symbol search and outlines

workspace_symbols({query, limit?}) accepts a nonblank query of at most 200 code points, without control characters. It forwards it unchanged. Matching is ASCII-case-insensitive subsequence matching, not natural-language ranking, regex or exhaustive discovery. Model aliases may be quoted. XML IDs use xmlid. plus the local ID, such as xmlid.probe_form—not an invented module-qualified alias. OWL names use template. plus the template name.

document_symbols({path, limit?}) returns a flat preorder outline with response-local id, parentId, depth, rooted ranges and optional selection ranges. Supported suffixes: .py, .pyi, .xml, .js, .ts; JS/TS needs tsserver. XML is an element outline, not a reconstructed business-model tree. Upstream duplicates and whole-declaration selection ranges are preserved.

Both default to limit 100; caller range 1–1000, also constrained by maxLocations. Budgets: 10,000 inspected nodes, document depth 32, name/container length 2,048 code points, structured response 256 KiB. Invalid paths/ranges or malformed responses fail explicitly. Count/payload caps report truncation. These caps do not bound all upstream work before a response.

Results observe loaded analysis state. Loading, unavailable, unsupported and failed outcomes differ from successful empty observations. Neither readiness nor an empty outline proves exhaustive coverage or completed rebuilds. Read returned source before using it as a precise navigation anchor.

File diagnostics

file_diagnostics({path, waitMs?}) observes push publications; waitMs is 0–30000, default 0. Inspect status, error, truncated, documentVersion, publishedVersion, freshness and timedOut together:

• not_received: no publication; received: a publication, possibly empty.

• stale: an earlier document observation; timed_out: wait expired without a publication. An expired wait can also leave uncertain/stale data.

• A positive wait returns early for a matching document version, but that is not finality: OdooLS can publish empty findings before findings at the same version. Use bounded retries when checking for a specific issue.

• clean: null is intentional. Empty findings never prove correctness or replace targeted tests/runtime validation.

At most 100 findings, with messages capped at 4,096 UTF-16 units. In 0.3.0, code is an exact string or signed 32-bit integer; source is optional. Optional strings are limited to 256 UTF-16 units. Invalid/oversized metadata is omitted with metadataOmitted and aggregate truncation signaling—not shortened into a false identifier. Missing source is not invented. Nested URL/related-information and opaque data remain excluded. All diagnostic text/metadata is untrusted data.

Explicit configuration for nonstandard workspaces

Discovery is the simplest setup. Use explicit configuration when discovery is ambiguous, when core/addons live outside a conventional tree, or when you need to increase startup timeout. You need two files: adapter JSON and OdooLS TOML. Examples below use Python-only analysis to avoid unnecessary tsserver setup. Verify the installed runtime first, then select its binary explicitly: managed runtimeDir automatically enables its tsserver and cannot be combined with disable_javascript = true in the current adapter.

Create adapter.json, replacing every path with an absolute path. This example selects the 0.3.0 / 1.6.2 pair:

{
  "workspace": "/absolute/path/to/user-root/work",
  "binary": "/absolute/path/to/user-root/.local/share/odools-mcp/runtime-1.6.2/odoo_ls_server",
  "config": "/absolute/path/to/user-root/work/odools.toml",
  "profile": "default",
  "allowedRoots": [],
  "startupTimeoutMs": 300000
}

Create odools.toml beside it:

[[config]]
name = "default"
odoo_path = "/absolute/path/to/user-root/work/odoo"
addons_paths = [
  "/absolute/path/to/user-root/work/odoo/odoo/addons",
  "/absolute/path/to/user-root/work/odoo/addons",
  "/absolute/path/to/user-root/work/my-addons",
  "/absolute/path/to/user-root/work/OCA-repository",
]
python_path = "/absolute/path/to/your/venv/bin/python"
stdlib = "/absolute/path/to/user-root/.local/share/odools-mcp/runtime-1.6.2/typeshed/stdlib"
disable_javascript = true

odoo_path is the checkout containing odoo-bin and odoo/release.py, not its inner odoo/ package. addons_paths contains directories whose children are addon modules; omit nonexistent entries and include the standard/custom addon repositories your code needs. The JSON profile must match TOML name.

The JSON workspace is the root for MCP input paths. If Odoo or another source root is outside it, add that directory to allowedRoots to permit returned navigation targets; this does not permit out-of-workspace inputs. Relative JSON paths resolve against the MCP process working directory, not the adapter JSON location. Use absolute paths in both files to avoid ambiguity; no $HOME/~ or upstream TOML path-template expansion is performed by adapter checks. With XDG or a nondefault runtime, use the same installed path in JSON and TOML. These paths match both the 0.3.0 release route and a verified-version 0.3.0 source build. Do not mix them with a legacy 0.2.0 CLI or merely change a version string.

Start with the selected adapter executable:

"$NODE_BIN" "$ADAPTER_CLI" serve --config /absolute/path/to/adapter.json

Use those same arguments in your MCP client. --config and --discover-workspace are mutually exclusive; unknown, duplicate, positional, missing-value and cross-mode arguments are rejected.

Optional JavaScript / OWL in explicit mode

For managed JS/OWL analysis, replace JSON binary with:

"runtimeDir": "/absolute/path/to/user-root/.local/share/odools-mcp/runtime-1.6.2"

Then change the selected TOML profile to:

disable_javascript = false
tsserver_command = "tsserver"
ts_check = false

The managed runtime supplies its verified TypeScript 6.0.2 launcher directory on the backend PATH. Node must also be available on PATH for that launcher's shebang; starting the adapter with an absolute Node path alone does not ensure this. Do not also specify binary, tsserver or tsserverVersion with runtimeDir. Discovery is another option: it generates its own shim and configuration. Explicit-binary JS mode instead requires a separately pinned tsserver and tsserverVersion: "6.0.2"; use it only when intentionally managing those assets. The structural examples in examples/adapter-managed.json and examples/adapter-explicit.json are templates, not complete workspaces or replacements for a matching TOML profile.

Client setup

The examples target OpenCode V2, Claude Code (not Claude Desktop), and OpenAI Codex CLI (not Codex web or the OpenAI API). Register only the workspace you intend to expose. Avoid a global fixed-workspace configuration if you switch between unrelated customers; use project-local configuration or per-project servers.

OpenCode V2

Follow the OpenCode V2 MCP documentation. Replace the paths; this is the complete release-target example (requires the 0.3.0 assets to be published and installed as above):

{
  "mcp": {
    "servers": {
      "odools": {
        "type": "local",
        "command": [
          "/absolute/path/to/node",
          "/absolute/path/to/user-root/.local/share/odools-mcp/releases/0.3.0-manual/node_modules/@pyming/odools-mcp/dist/cli.js",
          "serve", "--discover-workspace",
          "--workspace", "/absolute/path/to/work",
          "--python", "/absolute/path/to/your/venv/bin/python"
        ]
      }
    }
  }
}

For explicit configuration, retain the same two executable entries and replace the rest with "serve", "--config", "/absolute/path/to/adapter.json". When intentionally running a source build, substitute its absolute CLI path. examples/opencode-v2.jsonc shows the shorter PATH-based project-local form; it assumes you have separately configured that executable. An optional location-activation plugin is an optimization, not a dependency.

Claude Code

Following the Claude Code MCP documentation, register the selected absolute executables with a fixed explicit workspace/config:

claude mcp add --transport stdio --scope user odools -- \
  /absolute/path/to/node \
  /absolute/path/to/user-root/.local/share/odools-mcp/releases/0.3.0-manual/node_modules/@pyming/odools-mcp/dist/cli.js \
  serve --config /absolute/path/to/adapter.json

This is user-scoped: use the client's project scope instead if the fixed workspace should not apply to all projects. Inspect/remove with claude mcp list, claude mcp get odools and claude mcp remove odools.

OpenAI Codex CLI

Following the Codex MCP documentation and CLI reference:

codex mcp add odools -- \
  /absolute/path/to/node \
  /absolute/path/to/user-root/.local/share/odools-mcp/releases/0.3.0-manual/node_modules/@pyming/odools-mcp/dist/cli.js \
  serve --config /absolute/path/to/adapter.json

Inspect/remove with codex mcp list, codex mcp get odools and codex mcp remove odools.

Startup, readiness and troubleshooting

Connecting starts the lightweight adapter, not OdooLS. The first supported semantic call performs one shared cold activation; later calls reuse it. Status is diagnostic and never activates the backend or resumes a failed activation.

Large-tree cold startup can be substantial. Earlier measurements of startup exceeding four minutes or 1.3–1.5 GiB resident memory were historical 1.5.2 observations—not guarantees or current 1.6.2 measurements. A larger timeout cannot fix an invalid workspace or unsupported relation.

After activation, 0.3.0 status.backendCapabilities reports allowlisted server identity, UTF-16 and static provider support. providers: null means unobserved; each observed provider is supported, unsupported or omitted. Advertisement is not proof of language-specific behavior, completed indexing or runtime integrity revalidation. Pull-diagnostic capability does not gate push file_diagnostics; completion/resolve advertisement exposes no completion tool. Restart/stop invalidates the observation. The client does not opt into dynamic registration and refuses reverse edit requests.

Updates, rollback and offline installation

Keep the previous adapter and its compatible runtime. Extract a new adapter side by side, install/verify its exact runtime with that adapter, test the intended workflow, then change the client command and reconnect. Never unpack over the old installation. Running MCP processes retain loaded code until reconnect.

For legacy rollback, restore the retained 0.2.0 / OdooLS 1.6.1 client command and matching runtime/config, then reconnect. Keep its adapter directory (for example, releases/0.2.0-manual) and runtime-1.6.1 separate from the primary 0.3.0 / OdooLS 1.6.2 pair. A 0.2.0 adapter can verify its approved 1.6.1 installation; 0.3.0 requires 1.6.2. Older installer identities are not blanket authorization for different backend assets. Neither a package version nor a local build alone is proof of release provenance.

Offline runtime installation requires all three exact pinned archives from a trusted source. Use your selected adapter and its matching runtime version:

"$NODE_BIN" "$ADAPTER_CLI" install-runtime \
  --version 1.6.2 --runtime-dir "$RUNTIME_DIR" \
  --odools-archive /absolute/path/to/odoo-linux-x86_64-1.6.2.tar.gz \
  --typeshed-archive /absolute/path/to/1.6.2/typeshed.zip \
  --typescript-archive /absolute/path/to/typescript-6.0.2.tgz

This uses the primary 0.3.0 / 1.6.2 pair and its matching OdooLS/typeshed archives; TypeScript stays 6.0.2. Set RUNTIME_DIR to that pair's installed path as above. Legacy rollback installation instead requires the 0.2.0 adapter and its exact 1.6.1 archives/runtime path. Do not guess flag names. Runtime CLI emits JSON and 0.3.0 rejects unknown/incomplete flags before installation. No serve-time installation or implicit network fallback is promised for missing runtime assets.

Discovery behavior and cleanup

Discovery is conservative: it uses directory/manifest structure and safe literals such as auto_install = False; it does not import Odoo, execute project code, run Git/Docker/network commands or evaluate arbitrary Python. Non-auto-installable addon folders remain valid source. Exposing the same addon via distinct physical search roots is ambiguous and fails; repeated paths to the same canonical folder are deduplicated. Symlink escapes and ambiguous cores fail closed.

Generated TOML and the tsserver shim live in a private adapter-owned temporary directory. Normal shutdown/startup-failure cleanup is best-effort and idempotent; not every removal failure is reported. SIGKILL or other abnormal termination can leave directories behind. Session logs are removed only when adapter-created; operator-supplied log directories are never deleted. Do not automatically remove unfamiliar directories or unrelated processes when troubleshooting.

Why a separate adapter?

Odoo development benefits from complementary evidence:

• Graph or semantic indexing supports conceptual discovery, architectural understanding and impact analysis.

• Exact text and source inspection supports exhaustive verification of literal names, XML IDs, strings and implementation details.

• Live Odoo/runtime inspection is authoritative for registry state, database data, access rules, and effective inherited views.

• OdooLS position-based semantics adds supported code relationships and bounded known-name lookup—not installed/compiled runtime truth.

OdooLS is a focused navigation source, not a natural-language discovery system. The adapter offers local stdio MCP to clients without a suitable active native LSP runtime/tool surface; it does not replace source or live-runtime inspection. Keeping a separate repository preserves a small protocol and security boundary. The design rejected duplicating Odoo-specific semantics inside graph or indexing engines, embedding or permanently forking OdooLS, and unrestricted generic LSP passthrough. An actual upstream issue should preferably have its fix contributed upstream rather than silently patching the managed runtime.

Runtime selection is evidence-driven. Official 1.6.2 stable fixes orphan processes after client disconnect and @api.returns instance evaluation. The 0.3.0 runtime pins commit bf31b419609549a6a5e469c5dfb4da877b82efea; TypeScript stays 6.0.2. OdooLS remains official and unmodified. These are narrow fixes, not a new conceptual-search API. Native 0.3.0 acceptance covers the version-specific API on genuine Odoo 18 source, not a fabricated Odoo 19 decorator.

Security, license and contributing

This practical-local threat model trusts the invoking account, development source, configuration, configured roots, selected executables and dependencies. Workspace input paths are confined; returned paths are restricted to configured roots; requests, results, watching and restart resources are bounded. This is not a sandbox against hostile users, malicious workspaces or compromised dependencies. Do not expose the stdio endpoint as a network service. See SECURITY.md.

Maintained by Extreme Micro SL hola@pyming.com, independently of Odoo S.A. and the OdooLS maintainers; no affiliation or endorsement is implied. Adapter: AGPL-3.0-or-later. OdooLS, TypeScript and typeshed retain their own licenses; see THIRD_PARTY_NOTICES.md.

Contributions: CONTRIBUTING.md. Report vulnerabilities privately to hola@pyming.com, not in public issues with secrets or customer source.