Skip to content

odoo-work-cli mcp

NAME

odoo-work-cli-mcp - Run the MCP server on stdin/stdout (started by the MCP client)

SYNOPSIS

odoo-work-cli mcp [--read-only] [--secrets VALUE]
odoo-work-cli mcp COMMAND [OPTIONS]

DESCRIPTION

Run a Model Context Protocol (MCP) server on standard input and output.

The MCP client (Claude Code, an IDE, any agent host) starts it as a child process and talks newline-delimited JSON-RPC 2.0 with it: initialize, ping, tools/list and tools/call. There is no port and no daemon. Protocol revisions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05 are supported.

Every tool is one command of this CLI. A call runs that command in-process with --json, so validation, output fields and error kinds are exactly those of the CLI. Read tools: whoami, projects, tasks, entries, timesheets, clock_status, clock_list. Write tools: entries_add, entries_update, entries_delete, clock_in, clock_out, clock_add, clock_edit. The tools carry the MCP annotations readOnlyHint, destructiveHint and idempotentHint; entries_update, entries_delete and clock_edit are destructive.

A failed call is not a protocol error: it is a tool result with isError set and the JSON error envelope {"error":{"kind":"…","message":"…"}}. Results larger than 32 KiB come in pages; the second content item carries the cursor of the next page.

Configuration and secrets load on the first tool call that needs them, not at start: the server starts and lists its tools even with 1Password locked, and such a call reports secrets_locked. The next call tries again. Once 1Password has answered, the resolved secrets are kept for the life of the server, even when the Odoo login fails (network), so 1Password is asked at most once; an auth error discards them and the next call resolves again. With --secrets eager (or ODOO_WORK_CLI_MCP_SECRETS=eager) the secrets resolve at server start, so the 1Password prompt comes when the client starts; if that fails the server still starts and calls report secrets_locked. The connection is kept for the life of the server. The global flags --config and --backend given before mcp apply to every call.

Nothing is written to standard output except protocol messages; standard error stays empty.

Subcommands:

odoo-work-cli mcp print
Print the MCP client configuration for this server.

OPTIONS

--read-only

Serve only the read tools (no entries_add, entries_update, entries_delete, clock_in, clock_out, clock_add, clock_edit).

flag; optional

--secrets VALUE

When to resolve 1Password secrets: lazy (first tool call, default) or eager (at server start); env ODOO_WORK_CLI_MCP_SECRETS.

string; optional; env: ODOO_WORK_CLI_MCP_SECRETS

GLOBAL OPTIONS

--backend BACKEND

BACKEND: odoo or fake (offline, made-up data; env ODOO_WORK_CLI_BACKEND).

string; optional; default: odoo; env: ODOO_WORK_CLI_BACKEND

--config FILE

Read only the config FILE (skip discovery).

string; optional

-h, --help
Print the help of the command and exit.

OUTPUT

Only MCP protocol messages, one JSON-RPC 2.0 response per line on standard output. A tool result's first content item is the --json output of the command; see the MCP tool reference.

ENVIRONMENT

ODOO_URL
Odoo server URL; overrides url from the config files.
ODOO_DATABASE
Odoo database name; overrides database.
ODOO_USERNAME
Odoo login, usually an e-mail address; overrides username.
ODOO_PASSWORD
Odoo API key, used for XML-RPC. Despite the name, not the login password.
ODOO_WEB_PASSWORD
Odoo login password, used for the web session of clock in and clock out.
ODOO_TOTP_SECRET
TOTP secret (base32 or otpauth:// URL) for accounts with two-factor authentication.
ODOO_OP_TIMEOUT
Timeout of the 1Password call that resolves [op_secrets], a Go duration; default 5s.
ODOO_WORK_CLI_NO_OP
If 1, true, yes or on, [op_secrets] is ignored and the 1Password CLI is never called.
ODOO_WORK_CLI_BACKEND
Backend, odoo (default) or fake; --backend overrides it.
ODOO_WORK_CLI_FAKE_STATE
State file of the fake backend; default odoo-work-cli-fake-state.json in the temporary directory.
XDG_CONFIG_HOME
Base directory of the global config file; default ~/.config.
ODOO_WORK_CLI_MCP_SECRETS
When the MCP server resolves 1Password secrets: lazy (first tool call, default) or eager (at server start); mcp --secrets overrides it.

FILES

~/.config/odoo-work-cli/config.toml
Global configuration ($XDG_CONFIG_HOME/odoo-work-cli/config.toml if XDG_CONFIG_HOME is set). Created by odoo-work-cli config install.
.odoo-work-cli.toml
Configuration of a directory tree. Every such file from the filesystem root down to the current directory is merged over the global file, the deepest last. --config FILE loads only FILE instead.
$TMPDIR/odoo-work-cli-fake-state.json
State of the fake backend (--backend fake); ODOO_WORK_CLI_FAKE_STATE sets another path. Delete it to start over with the seed data.

EXIT STATUS

0 on success, 1 on any error, including usage errors. The error is printed as "Error: TEXT" on standard error.

Error kinds this command can fail with:

auth
Authentication failed: wrong API key or login password, TOTP rejected.
validation
Invalid input: unknown flag, bad argument, malformed date, time or hours, a time in the future, an unknown project.
network
Odoo cannot be reached: DNS, connection refused, timeout, TLS.
config
The local configuration is missing or invalid.
secrets_locked
1Password is locked or unreachable, so op:// references could not be resolved.
internal
Anything else: an unexpected Odoo response or a bug.

EXAMPLES

Register the server for Claude Code (user scope):

$ claude mcp add --scope user odoo-work-cli -- odoo-work-cli mcp

Only the read tools, against the offline fake backend:

$ odoo-work-cli --backend fake mcp --read-only

Ask 1Password at client start instead of in the middle of a task:

$ claude mcp add --scope user odoo-work-cli -- odoo-work-cli mcp --secrets eager

One request by hand:

$ echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | odoo-work-cli mcp

SEE ALSO