odoo_mcp
Odoo MCP server for OpenCode
本工作区附带一个本地 stdio MCP 服务器(odoo_mcp),它将你自托管的 Odoo 项目任务、讨论记录(chatter)和工时记录以九个类型化工具的形式暴露出来,供 agent(智能体)直接调用。同一仓库仍保留原始的 odoo_tasks.py CLI——行为不变——它与 MCP 服务器共享服务层。
前置条件
Python 3.10+(工作区基于 3.12 开发)
uv 已在 PATH 中(如缺失,执行
pip install uv)
一次性安装全部依赖:
uv syncRelated MCP server: MCP Server for Odoo
凭据(环境变量)
变量 | 用途 | 默认值 |
| Odoo 实例的基础 URL |
|
| 数据库名 |
|
| 你的登录邮箱 | 必填 |
| 密码或外部 API 密钥 | 必填 |
ODOO_URL 必须是绝对 HTTPS URL,确保凭据绝不会通过明文 HTTP 传输。
强烈建议使用 API 密钥而不是密码(Odoo:首选项 → 账户安全 → 新建 API 密钥):它可以被撤销,且不能用于网页登录。将 .env.example 复制为 .env,填写内容,再加载到你的 shell 中,或者按照你管理密钥的方式设置这些变量。当工作区根目录存在 .env 时,MCP 服务器和 CLI 辅助工具都会自动加载它;已经由 OpenCode 或 shell 设置的环境变量优先。切勿提交 .env。
插值注意事项: opencode.json 使用 {env:VAR} 占位符。如果某个变量在 OpenCode 启动时缺失,它会变成空字符串,然后每次工具调用都会以清晰的错误信息失败,指出缺失的变量(Missing required environment variables: ODOO_USERNAME, ...),而不是把错误的凭据发往任何地方。任何值都不会被回显到日志或结果中。
如何向 OpenCode 注册
本工作区的 opencode.json 已经包含:
{
"mcp": {
"odoo": {
"type": "local",
"command": ["uv", "run", "python", "-m", "odoo_mcp"],
"environment": { "...": "{env:ODOO_*} placeholders" },
"enabled": true
}
}
}OpenCode 在启动时加载配置——在修改凭据或此文件之后,退出并重启 OpenCode 即可使其生效。服务器只在每次会话中通过 stdio 生成一次;没有任何网络端口在监听。
工具
修改类工具默认立即执行;其中每个工具都可接受 dry_run=true 标志,该标志会先返回预览而不写入任何内容。
工具 | 功能说明 |
| 分配给你的任务;可按项目、阶段、状态、截止日期过滤 |
| 单个任务的完整详情(包含计划/记录的工时) |
| 设置名称/描述/优先级/截止日期/工时/状态/阶段; |
| 发布到任务的讨论记录(chatter)中(关注者会收到通知) |
| 该服务器上有效的工作流状态码 + 哪些是终态 |
| 任务阶段 的 ID/名称,用于过滤 |
| 你的工时记录;可按任务或最近的天数过滤 |
| 在任务上记录工时时(日期默认为今天) |
| 修改某条记录的工时/日期/描述/任务 |
状态码因 Odoo 构建版本而异——先调用 get_task_states 而不是猜测;无效状态会被拒绝并附带有有效状态码,再返回安全使用。
验证安装
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 intactstdio 握手过程本身由 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.-