Connect an MCP client¶
How to give an agent host that speaks the Model Context Protocol (Claude Code, an IDE, a desktop app) the timesheet and attendance commands as MCP tools.
odoo-work-cli mcp is an MCP server on standard input and output. The client
starts it as a child process; there is no port and no daemon. Every tool is one
command of the CLI, run with --json, so the fields and error kinds are the
ones you already know. The full list is in the
MCP tool reference.
Register the server¶
odoo-work-cli mcp print --command prints exactly this line. Check it
with claude mcp list; the server shows as connected.
If the client does not search PATH, use an absolute path:
odoo-work-cli mcp print --binary "$(command -v odoo-work-cli)".
The server reads the same configuration as the CLI (config files, environment,
1Password). Global flags go before mcp and apply to every tool call, for
example odoo-work-cli --config ~/work.toml mcp.
Read only¶
--read-only serves only the read tools (whoami, projects, tasks,
entries, timesheets, clock_status, clock_list). The write tools are
not listed and cannot be called. mcp print --read-only adds the flag to the
printed configuration.
What the agent sees¶
- Annotations. Read tools carry
readOnlyHint.entries_update,entries_deleteandclock_editcarrydestructiveHint: they overwrite or remove data. Clients use these to decide what needs a confirmation; let the read tools run freely and confirm every write. - Dry runs.
entries_addandentries_updatetakedry_run: true: the entry is resolved and checked, duplicates are listed, nothing is written. The server instructions tell the agent to propose with a dry run first. - Errors. A failed call is a normal tool result with
isError: trueand the error envelope:{"error":{"kind":"not_found","message":"timesheet entry 424242 not found"}}. Bad arguments arevalidationand name the argument, not a flag. - Pages. A result over 32 KiB comes in pages; the second content item
says which page and gives the
cursorfor the next.
1Password and startup¶
The server starts without loading the configuration or secrets. They load on
the first tool call that needs them, as in the CLI. If 1Password is locked,
that call returns secrets_locked and the server keeps running: unlock
1Password and the next call loads.
Once 1Password has answered, the resolved secrets are kept for the life of the
server, even when the Odoo login then fails (network, timeout): 1Password is
asked at most once per server process. Only an auth error (a rotated API key
or password) discards them; the next call resolves again, once.
To have the prompt when the client starts instead of in the middle of a task, resolve eagerly:
--secrets eager (or ODOO_WORK_CLI_MCP_SECRETS=eager) resolves the secrets
before the first request. If that fails the server still starts, and calls
report secrets_locked as before. For a setup without any prompt during work,
see 1Password prompts.
Try it without Odoo¶
Register the server against the offline fake backend:
Every tool then works with made-up data; see Test without Odoo.
To watch the protocol by hand:
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"projects","arguments":{"search":"alpha"}}}' \
| odoo-work-cli --backend fake mcp
Agents with a shell tool¶
Coding agents that can run commands need no MCP server: give them the guide
from llm --skill and let them call the CLI. See
Use it from a coding agent. Both ways use the same commands
and the same JSON; the MCP server is for hosts that only call tools, or when
you want the client's per-tool permissions and the --read-only switch.