odoosh-mcp

MCP server to administer odoo.sh projects agentically: create stagings, download backups, manage settings/collaborators/submodules, run code profiling (flamegraphs), read metadata (production DB size, worker count, staging slots), consume audit logs, manage builds, tail logs, and reach the SSH-only operations (restart, raw logs, SQL) — all through one permission-gated tool surface, inspired by the structure of odoo-mcp-multi.

Status: v0.0 in active development. See docs/superpowers/specs/2026-09-04-odoosh-mcp-v0-design.md for the full design and docs/superpowers/plans/ for the task-by-task implementation plan.

Why this exists

The odoo.sh web UI has no public API. Every route this server calls was reverse-engineered from the platform's own OWL frontend bundle and verified live against a disposable trial project. Full methodology and the 58-route catalog live in docs/00-discovery.md and docs/01-api-surface.md.

Three facts shape the whole design (details in docs/02-write-operations.md and docs/03-spikes.md):

1. Two HTTP planes, two credentials — the control plane (www.odoo.sh/app/*, cookie auth) and the worker plane (<build.worker_url>/paas/*, per-project access-token auth) do not share credentials.

2. Writes lie about success, and there is no single way to confirm one. A write can return HTTP 200 with a null body while the change never applied — but live spikes proved the audit log does not cover every route either (docs/03-spikes.md §7). This server uses three confirmation strategies, matched per operation family: settings and branch-lifecycle writes are confirmed against audit_logs growth; backup, submodule, profiler and collaborator writes are re-verified by re-reading the affected resource's own listing (the project's backups, get_settings().submodules, flamegraph/list, get_settings().users) — for submodules and the profiler because live spikes proved there is no audit trace, for backups because the listing is direct evidence the dump exists, and for collaborators because audit coverage was never verified either way and an unverified assumption is not a confirmation; SSH-plane operations (restart_build, tail_log, search_log, run_sql, ssh_exec) can only be confirmed by the SSH command's own stdout and exit code, since audit_logs records nothing more specific than "a shell was opened."

   A write that its strategy could not confirm is returned as success: false, with the evidence gathered so far under data. An unconfirmed write did not happen, whatever the HTTP 200 said, so it is never reported as a success with a flag buried inside it.

3. Restart and raw log tailing have no HTTP route; SQL needs no special access route either. odoo.sh's own UI tells you to run odoosh-restart in the webshell for the former. For SQL, odoosh-sql-access turned out to be for external BI-tool access on dedicated servers only (docs/03-spikes.md §4) — the build's own shell already exports PGDATABASE/PGUSER/ PGPASSWORD/PGHOST, so run_sql simply runs psql -c "<sql>" over the same SSH session on any project tier.

Safety model

• write_scope — each profile carries an allow-list of project names it is permitted to write to (see odoosh_mcp/config.py). A write against a project outside that scope fails before any HTTP request is made.
• Risk tiers — every tool is registered in TOOL_REGISTRY with one of read, write_safe (reversible, no side effect outside the project), write_external (touches something outside odoo.sh itself, e.g. GitHub, a subscription, another person's access), destructive (irreversible), or ssh_exec (unrestricted shell access). See the tool catalog below for each tool's tier.
• confirm=True — every write_external, destructive, and ssh_exec tool refuses to run without an explicit confirm=True parameter; omitting it always fails safely with no side effect. run_sql is the one exception worth calling out: it is registered write_safe (opening a psql session on a build is a write-tier capability, and both paths are write_scope-gated), it defaults to read-only by running psql with PGOPTIONS=-c default_transaction_read_only=on so the connection is read-only, and it only requires confirm=True when called with read_only=False. That guard is best-effort, not a sandbox — SQL that resets the GUC itself escapes it, which is exactly why the tool is scope-gated as well.
• Account-level tools take no project, so write_scope cannot restrain them. add_ssh_key is therefore write_external and requires confirm=True: the key it registers grants SSH on the build of every project the account can reach, including projects deliberately left out of the profile's write_scope, and the grant outlives the session.
• Nothing here is anonymous. Every action taken through this server is also audited on odoo.sh itself under the human account that owns the configured session_id cookie — an agent operating this MCP signs with that person's name on the platform's own audit log (docs/03-spikes.md §6), whether or not that particular write happens to show up in get_audit_logs.

write_scope and permissions are managed with odoosh-mcp profile scope and odoosh-mcp profile permissions; run either with no flags to see the current value. Clearing a scope grants writes on every project the session can reach, so it requires an explicit --yes.

Installation

pip install odoosh-mcp-server

The distribution is odoosh-mcp-server; it installs two console scripts, odoosh-mcp (the canonical one, used throughout this README) and odoosh-mcp-server, which are the same CLI; the importable module is odoosh_mcp. PyPI already hosts an unrelated odoo-sh-mcp -- a different tool, which reads ORM metadata over XML-RPC rather than administering the platform -- and PyPI treats the two names as the same once separators are stripped, so this one carries the suffix.

Importing the session cookie from a local browser needs one extra dependency, declared as the optional browser extra:

pip install "odoosh-mcp-server[browser]"

Everything else works without it. To install an unreleased revision instead:

pip install "git+ssh://git@git.vauxoo.com/hugho-ad/odoosh-mcp-server.git@main"

Configuration

odoosh-mcp profile add --name my-account --session-id <paste from the browser cookie>
odoosh-mcp auth login --profile my-account --from-browser   # needs the browser extra
odoosh-mcp auth status --profile my-account

odoo.sh issues no API token: signing in is GitHub OAuth against odoo.sh's own OAuth application, and the credential it produces is a session cookie. The callback lands on odoo.sh rather than on a port this server could listen on, so there is no way for the server to run the login itself. What it can do is read that one cookie back from the browser that already holds it (--from-browser reads only the session_id cookie, only for the odoo.sh host), and tell you when it has gone stale.

auth status reports whether the session is alive, how old it is, where it came from, and whether odoo.sh's GitHub grant covers the repository routes. It never prints the cookie — only a six-character fingerprint, which is enough to confirm that a re-login actually replaced it.

Profiles are stored in ~/.config/odoosh-mcp/profiles.json (directory mode 700, file mode 600).

When a tool answers with a remediation

An expired session and an insufficient GitHub grant both come back as an ordinary error envelope carrying a remediation object that names the fix:

{"success": false, "error": "The token does not provide the required scope ...",
 "route": "/app/branch/5118230/fork",
 "remediation": {"action": "authorize_github",
                 "url": "https://github.com/login/oauth/authorize?...",
                 "scopes": ["read:user", "user:email", "repo"],
                 "hint": "call authorize_github, then retry"}}

create_staging, merge_branch and add_submodule need GitHub scopes that a plain odoo.sh login does not request, and the scope set differs per route, so the URL always comes from odoo.sh's own error rather than from a constant in this package. Run:

odoosh-mcp auth authorize-github --profile my-account

It prints the scopes odoo.sh is asking GitHub for, opens the authorization page after you confirm, and then polls until the grant lands. The MCP tool of the same name never opens a browser unless it is called with open_browser=true — an agent gets the URL to hand to a human, not control of somebody's desktop.

Usage

As an MCP server (stdio):

odoosh-mcp serve

From the command line directly:

odoosh-mcp run get_project --param project=my-project
odoosh-mcp run list_branches --param project=my-project --json

Tool catalog

Generated from TOOL_REGISTRY by scripts/render_tool_catalog.py — re-run that script and paste its output here whenever a tool is added, renamed, or has its tier/confirm gate changed, so this table cannot drift from what the server actually registers.

One side effect worth knowing before calling download_backup on a storage-constrained project: triggering a dump also leaves a manual backup entry on odoo.sh (observed live 2026-09-05), which counts against storage until it expires on its own — there is no route to delete it.

Development

pyenv virtualenv 3.12 odoosh-mcp
pyenv activate odoosh-mcp
pip install -e ".[dev]"
pytest
ruff check odoosh_mcp/

Integration tests that hit a live odoo.sh project are opt-in and read-only by default — see tests/integration/ and the design spec §10. tests/integration/test_live_auth.py checks the authentication surface without writing anything or opening a browser.