odoo_mcp
Manage your self-hosted Odoo tasks, chatter, stages/states, and timesheets via local MCP tools; mutating tools support dry-run previews.
List your assigned tasks, with filters for project, stage, state, due dates, and inclusion of done/terminal tasks.
Get full details for a task by ID.
Update task fields (name, description/append, allocated hours, progress, priority, deadline, state, stage); dry-run preview available.
Post messages to a task's chatter.
Discover valid task workflow states and available task stages.
List your timesheet entries, filtered by task or recent days.
Create timesheet entries for a task (hours required; date defaults to today).
Update existing timesheet entries (hours, date, description, or move to another task).
README also advertises
create_task, but the provided schema does not include it.
Provides tools for interacting with a self-hosted Odoo instance, enabling agents to list, retrieve, and update tasks, post messages to task chatter, and manage timesheet entries.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@odoo_mcp what tasks are due this week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 ten 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 uvif missing)
Install everything once:
uv syncRelated MCP server: MCP Server for Odoo
Credentials (environment variables)
Variable | Purpose | Default |
| Base URL of your Odoo instance |
|
| Database name |
|
| Your login email | required |
| Password or external API key | required |
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.
Tool | What it does |
| Tasks assigned to you; filter by project, stage, state, due dates |
| Full detail of one task (planned/logged hours included) |
| Create a task in a project; optional description/priority/deadline/hours/stage; assignees default to you |
| Set name/description/priority/deadline/hours/state/stage; |
| Post to a task's chatter (followers get notified) |
| Valid workflow state codes on this server + which are terminal |
| Task stage ids/names for filtering |
| Your timesheet entries; filter by task or recent days |
| Log hours on a task (date defaults to today) |
| Change hours/date/description/task of an entry |
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 intactThe stdio handshake itself is covered by tests/test_stdio_smoke.py.
Available Tools
9 toolscreate_timesheetA
Log hours worked on a task (defaults to today); returns {"entry_id": id}.
hours must be > 0; date must be YYYY-MM-DD. With dry_run=true returns {"dry_run": true, "vals": {...}} without writing.
Inputs: hours (required), task_id (required), date, dry_run, +1 more.
get_taskA
Fetch one task by id with full detail fields (hours, progress, stage...).
Inputs: task_id (required).
get_task_statesA
List this server's valid task workflow states as {code, label, terminal}.
Inputs: no named parameters. Returns: result
list_my_tasksA
List the caller's Odoo tasks (tasks they are assigned to).
By default terminal states (done/cancelled/closed) are excluded; pass include_done=true to see everything. Optional filters: project_id, stage_id, exact state code, deadline window due_after/due_before (YYYY-MM-DD). limit=0 means no limit.
Inputs: limit, state, stage_id, due_after, +3 more. Returns: result
list_stagesA
List the task stages (project.task.type) available on the server.
Inputs: no named parameters. Returns: result
list_timesheetsA
List the caller's timesheet entries, newest first.
Optional filters: task_id restricts to one task; days restricts to the last N days; limit caps the row count (default 50).
Inputs: days, limit, task_id. Returns: result
post_task_messageA
Post a message to a task's chatter (followers get notified).
Returns {"message_id": id}, or {"dry_run": true, ...} with dry_run=true.
Inputs: message (required), task_id (required), dry_run.
update_taskA
Update mutable fields of a task; executes immediately unless dry_run.
Field args: name, description (replaces), append_description (appends to the existing description after a blank line), allocated_hours (planned effort), progress (0-100; computed field - prefer allocated_hours), priority (0 low .. 3 urgent), deadline (YYYY-MM-DD), state (workflow code from get_task_states), stage (exact stage display name). With dry_run=true returns {"dry_run": true, "vals": {...}} without writing.
Inputs: task_id (required), name, stage, state, +7 more.
update_timesheetA
Modify an existing timesheet entry; returns {"ok": true} on success.
Pass at least one of hours (> 0), date (YYYY-MM-DD), description or task_id (moves the entry, keeping its project consistent). With dry_run=true returns {"dry_run": true, "vals": {...}} without writing.
Inputs: entry_id (required), date, hours, dry_run, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct resource and action: tasks (get, list, update, message, states) and timesheets (list, create, update), plus stage listing. There is no overlap or ambiguity between tool purposes.
Tool names follow a consistent verb_noun pattern throughout: get_task, list_my_tasks, update_task, post_task_message, list_stages, create_timesheet, etc. Minor variation between 'get_task_states' and 'list_stages' is natural and still fits the pattern.
With 9 tools, the set is well-scoped. Each tool serves a clear purpose within the task and timesheet domain, and the count is in the ideal range for usability.
Task and timesheet operations cover the main read/update workflows, including states, stages, and messaging. However, there are notable gaps: no create_task, no delete_task, and no delete_timesheet, which prevents full lifecycle management.
Maintenance
Related MCP Connectors
Read, write and run Odoo actions from any AI app, as each user, with approval rules per colleague.
Connect AI to Odoo ERP 14-20: search, create, update and manage records in natural language.
Time tracking, tasks and team chat for humans and AI agents.
Odoo ERP for AI agents: hosted OAuth endpoint, gated writes, one endpoint for every instance.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to interact with Odoo ERP systems through natural language to search records, create entries, update data, and manage business operations. Supports secure authentication and configurable access controls for production environments.Mozilla Public 2.0
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to interact with Odoo ERP systems through natural language, allowing users to search, create, update, and manage business records like customers, products, and invoices across any Odoo instance.1Mozilla Public 2.0
- AlicenseAqualityBmaintenanceEnables AI agents to interact with Odoo ERP as the authenticated user, with tools for discovery, planning, and mutations bounded by user permissions.3656 npm2Apache 2.0
- FlicenseNot gradedqualityCmaintenanceEnables authenticated team members to manage Odoo projects, tasks, timesheets, and milestones through Claude, with per-user token-based authentication.-