odoo-bookkeeping-mcp

An MCP (Model Context Protocol) server that gives an LLM agent -- Claude, ChatGPT, or any other MCP-compatible client -- full read/write access to one Odoo instance's accounting (invoices, vendor bills, journal entries, payments, reconciliation, P&L/balance sheet/aged reports) and, if the instance has the project_budget_boq_sunderland addon installed, its BOQ/Project Budget data.

It is not an Odoo addon. It talks to Odoo the same way any external integration does: Odoo's standard /xmlrpc/2/* API, authenticated as a normal Odoo user via an API key. No code needs to be installed on the Odoo server.

⚠️ Read this before pointing it at a real database

This server was built with no restrictions by explicit request: every tool that can create, edit, post, or reconcile a real accounting record will do so immediately when called, with no draft/review/approval gate and no human-in-the-loop step. That is a deliberate choice, not an oversight -- but it means:

• A wrong or hallucinated tool call becomes a real entry in your books. A posted journal entry cannot be edited or un-posted -- correcting it needs a reversal or credit note (this server can do that too, but the original mistake still shows up in every report until it's reversed).
• Whoever/whatever can reach this server can act as its Odoo user. Give it a dedicated Odoo user (not an admin's personal login) scoped to exactly the access rights, companies, and record rules you want an agent to have -- Odoo's own security model is still the only thing standing between "the agent read this wrong" and "the books are wrong."
• Deletion (odoo_unlink) is the one thing still off by default -- see ODOO_MCP_ALLOW_UNLINK below. Everything else (create/write/post/ reconcile) is on by default per the request that led to this server.
• Treat the .env file / API key like a production database password, because functionally it is one.

What's inside

src/odoo_mcp/
  client.py     Odoo XML-RPC wrapper (auth, generic CRUD, error mapping)
  config.py     Reads connection + safety-valve settings from the environment
  server.py     MCP server entrypoint; registers every tool module below;
               dispatches to stdio or HTTP transport
  http_auth.py  Bearer-token ASGI middleware, used only in HTTP transport
  tools/
    generic.py     odoo_search_read / odoo_create / odoo_write / odoo_unlink /
                   odoo_call_method / odoo_fields_get -- works against ANY
                   model, the "no restrictions" escape hatch every other
                   tool module is really just a friendlier wrapper over.
    accounting.py   Customer invoices, vendor bills, journal entries,
                   posting, reversal, payment registration, reconciliation.
    reports.py      P&L, balance sheet, trial balance, general ledger,
                   aged receivable/payable -- computed from posted
                   account.move.line data (not Odoo's PDF report engine).
    boq.py          project.budget / project.budget.line: list/get budgets,
                   create/update BOQ lines, submit/approve/activate
                   workflow, budget-vs-actual. Only useful if your Odoo
                   instance has project_budget_boq_sunderland installed;
                   otherwise fall back to the generic tools for whatever
                   budgeting model it does have.
tests/           Unit tests against a mocked XML-RPC server (no live Odoo
                 instance is available while building this) -- verify
                 request shaping, auth caching, and error handling. They do
                 NOT prove your specific Odoo instance/version behaves
                 identically; test against a real (ideally staging) database
                 before trusting this in production.

Setup

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
# edit .env with your real Odoo URL / DB / username / API key
python -m pytest tests/ -v

Getting an Odoo API key

In Odoo: click your avatar → My Profile → Account Security → New API Key. Do this for the dedicated integration user you created for this server, not your own login.

Environment variables

See .env.example for the full list with comments. Required: ODOO_URL, ODOO_DB, ODOO_USERNAME, ODOO_API_KEY.

Safety valves (optional, all env-var controlled so you never need to edit code to change them):

Variable	Default	Gates
ODOO_MCP_ALLOW_UNLINK	false	odoo_unlink (permanent record deletion)
ODOO_MCP_ALLOW_POST	true	posting invoices/journal entries, registering payments
ODOO_MCP_ALLOW_RECONCILE	true	reconcile_lines

Transport (optional):

Variable	Default	Notes
ODOO_MCP_TRANSPORT	stdio	stdio or http
ODOO_MCP_BEARER_TOKEN	(none)	required when ODOO_MCP_TRANSPORT=http -- server refuses to start over HTTP without it
ODOO_MCP_HOST	127.0.0.1	HTTP bind address
ODOO_MCP_PORT	8000	HTTP bind port

Connecting it to Claude

Claude Desktop / Claude Code -- add to your MCP config (claude_desktop_config.json or the CLI's .mcp.json):

{
  "mcpServers": {
    "odoo-bookkeeping": {
      "command": "odoo-mcp",
      "env": {
        "ODOO_URL": "https://your-instance.odoo.com",
        "ODOO_DB": "your-db",
        "ODOO_USERNAME": "mcp-integration@yourcompany.com",
        "ODOO_API_KEY": "your-api-key"
      }
    }
  }
}

(Run pip install -e . first so the odoo-mcp command exists on PATH, or use the full path to python -m odoo_mcp.server instead of odoo-mcp.)

Running it on a server (HTTP transport, for ChatGPT or remote access)

ChatGPT's MCP/connector support (and any remote Claude session) needs a server reachable over HTTP, not a local stdio process. Set the transport and a bearer token, then run it:

export ODOO_MCP_TRANSPORT=http
export ODOO_MCP_BEARER_TOKEN=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))")
echo "Save this token -- callers must send it as: Authorization: Bearer $ODOO_MCP_BEARER_TOKEN"
odoo-mcp
# or: python -m odoo_mcp.server

This serves POST /mcp (streamable-HTTP) on ODOO_MCP_HOST:ODOO_MCP_PORT (default 127.0.0.1:8000), gated by a self-contained ASGI middleware (http_auth.py) that rejects any request without an exact Authorization: Bearer <token> match -- the server refuses to start over HTTP at all if ODOO_MCP_BEARER_TOKEN is unset, since this server has no other access control of its own.

Before pointing a real client at it:

• Keep the bind address at 127.0.0.1 and put a reverse proxy (nginx, Caddy, Cloudflare Tunnel) in front for TLS + a real domain -- this process speaks plain HTTP and does not terminate TLS itself.
• The bearer token is the entire network-facing security boundary here (Odoo's own access rights are the boundary behind it). Rotate it if it ever leaks, and don't put it in a URL, query string, or client-side code -- header only.
• Configure your MCP client (ChatGPT connector settings, or a remote Claude MCP config) to call https://your-domain/mcp with that bearer token as its auth header.

What is NOT here

• No Odoo module/addon changes -- this only uses Odoo's existing external API, so it works against any reasonably recent Odoo version without touching the target instance at all.
• No real Odoo test run -- this development environment has no reachable Odoo/Postgres instance. Everything above tests/ is verified with a mocked XML-RPC backend (request shaping, auth, error handling) and a live tool-registration smoke test against the actual MCP server object; none of it has been exercised against a real database. Test against a staging Odoo database before pointing this at production.
• No UI, no scheduling, no webhook listener -- it only responds to tool calls a connected MCP client makes.