Odoo MCP server for OpenCode

This workspace ships a local stdio MCP server (odoo_mcp) that exposes your self-hosted Odoo project tasks, chatter, and timesheets as nine typed tools an agent can call directly. The same repository still contains the original odoo_tasks.py CLI — unchanged behaviorally — which shares the service layer with the MCP server.

Prerequisites

• Python 3.10+ (workspace developed against 3.12)

• uv on PATH (pip install uv if missing)

Install everything once:

uv sync

Related MCP server: MCP Server for Odoo

Credentials (environment variables)

ODOO_URL must be an absolute HTTPS URL so credentials are never sent over cleartext HTTP.

An API key is strongly recommended over a password (Odoo: Preferences → Account Security → New API Key): it is revocable and cannot be used for web login. Copy .env.example to .env, fill it in, and load it into your shell, or set the variables however you manage secrets. The MCP server and CLI helper both auto-load a workspace-root .env when it is present; environment variables already set by OpenCode or the shell take precedence. Never commit .env.

Interpolation caveat: opencode.json uses {env:VAR} placeholders. If a variable is missing when OpenCode starts, it becomes an empty string, and every tool call will fail with a clear error naming the missing variable(s) (Missing required environment variables: ODOO_USERNAME, ...) instead of sending bad credentials anywhere. Values are never echoed to logs or results.

Registering with OpenCode

opencode.json in this workspace already contains:

{
  "mcp": {
    "odoo": {
      "type": "local",
      "command": ["uv", "run", "python", "-m", "odoo_mcp"],
      "environment": { "...": "{env:ODOO_*} placeholders" },
      "enabled": true
    }
  }
}

OpenCode loads config at startup — after changing credentials or this file, quit and restart OpenCode for them to take effect. The server is spawned once per session over stdio; nothing listens on any network port.

Tools

Mutating tools execute immediately by default; every one accepts a dry_run=true flag that returns a preview without writing anything.

State codes vary per Odoo build — call get_task_states first rather than guessing; invalid states are rejected with the list of valid ones.

Verifying the install

uv sync                                              # deps resolve
uv run pytest tests -q                               # protocol + service suites
uv run python -m unittest discover -s tests -v       # CLI characterization suite
uv run python odoo_tasks.py --help                   # legacy CLI still intact

The stdio handshake itself is covered by tests/test_stdio_smoke.py.