Odoo MCP

Odoo MCP

odoo-mcp 是面向工作流的 Odoo Enterprise MCP 服务。它提供只读能力发现、试算平衡表报告、应收账款和应付账款账龄报告、现金簿可见性、未匹配银行流水检测，以及仅生成方案的银行对账。它还提供范围受限、只读的 Payroll 证据，涵盖精确期间、批次、工资单、员工、薪资规则和 Payroll 工作条目，以及确定性的 Payroll 比较和异常审查。

初始会计版本还支持范围受限的发票、供应商账单、贷项通知单、付款登记和手动日记账工作流。默认情况下，变更类工具仅提供预览，且需要显式执行并使用幂等性机制。

内部 Odoo 适配器为会计和 Payroll 工作流提供范围受限、类型明确、按公司隔离的基础操作。它会强制执行固定的模型/操作允许列表，移除被拒绝的字段，规范化日期、小数、关系和游标分页，并将 Odoo 身份验证、权限和传输故障转换为安全错误。它不提供通用 CRUD 或 Odoo 配置界面。

支持的连接目标为 Odoo.sh 和可自托管的 Odoo Enterprise：

• 通过外部 JSON-RPC 支持 Odoo 18
• 通过 JSON-2 支持 Odoo 19

不支持其他 Odoo 版本、Odoo Online、Community 版和自定义分支。此软件包不是 Odoo 模块，也不提供通用模型 CRUD。

安装

产品和命令名为 odoo-mcp；PyPI 发行包名为 odoo-erp-mcp，因为 odoo-mcp 发行包名称归另一个项目所有。

pipx install odoo-erp-mcp
odoo-mcp --help

该软件包还提供 odoo-erp-mcp，作为 MCP Registry 客户端的兼容启动器。它启动的服务与 odoo-mcp 相同。

本地开发

需要 Python 3.11 或更高版本以及 uv。

Copy-Item .env.example .env.local
# Replace the placeholders in .env.local, then:
uv sync --locked --all-extras
uv run odoo-mcp --profile local --config config/config.example.yaml

本地开发使用 stdio。进程环境中的设置优先于 .env.local。切勿提交 .env.local。

远程配置

专用远程和共享托管使用与本地开发相同的服务、注册表、工作流和 Odoo 适配器，并通过 Streamable HTTP 提供服务：

uv run odoo-mcp --profile dedicated --host 127.0.0.1 --port 8000
uv run odoo-mcp --profile shared --host 127.0.0.1 --port 8000

专用远程从进程环境中读取其唯一的 Odoo 连接；它绝不会加载 .env.local。每个 /mcp 请求都必须携带由部署方签发的 HS256 bearer JWT。在 MCP 路由前，服务会验证其签名、固定的签发者、固定的受众、到期时间、签发时间、主题和客户端 ID；权限和公司授权仍由服务端管理。请配置 ODOO_MCP_AUTH_ISSUER、ODOO_MCP_AUTH_AUDIENCE，以及由机密存储提供、长度至少为 32 个字符的 ODOO_MCP_AUTH_SIGNING_KEY。

共享托管是同一镜像中的可运行开放注册应用。它提供 OAuth 发现、动态客户端注册、授权、令牌、撤销、浏览器注册、受保护资源元数据和 MCP 路由。应用会验证每个 Odoo 连接，让用户从 Odoo 返回的公司列表中选择，并对凭据加密存储，同时将每个令牌绑定到唯一一个活跃连接器。请根据 .env.shared.example 配置；其带版本信息的 256 位加密密钥必须来自由运营方控制的机密存储。配置缺失、密文无效、授权未激活、Odoo 目标不安全以及连接器绑定未授权时，系统都会拒绝请求。共享托管支持以下两种方式：使用持久化本地 SQLite 卷的单个可写进程，或使用经过验证的 PostgreSQL，并采用池化运行时连接和直连迁移连接。TLS、公共入口、监控和生产部署仍由运营方负责。

可复现的专用远程 Docker 和 systemd 模板、共享托管集成要求以及网络加固指南，请参阅 docs/deployment.md。请勿将示例 HTTP 监听器直接暴露到公共互联网。

持久化状态

odoo_mcp.storage.Storage 提供有序的 SQLite 和 PostgreSQL 迁移，以及按租户隔离的审计记录、提案、制品、幂等预留、能力快照和加密 Shared Hosted 连接仓库。审计行仅追加，并按租户通过 SHA-256 哈希链关联。幂等预留会绑定租户、公司、工具、密钥和请求负载，以支持 24 小时内重放；进行中和结果未知的请求会继续阻止执行，等待显式恢复。最终结果必须保留可重放的响应，并与预留时的公司一致。审计失败文本根据已注册的错误代码生成；不会持久化自由格式的上游错误文本。

SQLite 备份使用一致性快照。恢复时会写入新的目标位置，且只有在数据库完整性、迁移、租户审计链、幂等状态、能力数据和加密连接均通过验证后才会被接受。加密密钥必须单独备份和恢复。PostgreSQL 使用数据库级迁移序列化，并保留相同的仓库、OAuth、审计、幂等、加密和生命周期契约。

默认情况下，服务会将本地持久化状态存储在 .odoo-mcp/state.sqlite3。使用 --storage <path> 选择其他 SQLite 文件。成功的会计报告会以原子方式持久化其 Markdown 制品和精简的审计结果；失败和被拒绝的报告调用会在解析出隔离身份后，持久化不包含敏感信息的失败审计。

写入安全

odoo_mcp.policy.WriteSafetyCoordinator 是具备写入能力的工作流必须经过的边界。它会在准备工作流之前，强制执行注册表风险元数据、已解析身份、权限、公司和能力门控。调用默认仅生成预览。执行需要显式设置 dry_run: false 并提供非空幂等密钥，随后会预留该密钥并追加尝试审计，然后才进行新鲜状态验证和 Odoo 修改。

成功、拒绝、冲突、重放、已知失败和未知结果彼此区分，并能在重启后安全重放。对结果不确定的修改绝不会自动重试；如果可能已完成修改后结果持久化失败，进行中的预留仍会阻止重复执行。能够证明未发生修改的 Odoo 权限拒绝会作为结构化的已知失败处理。审计文本和响应文本会隐藏原始异常详情。

人工确认由 MCP 客户端宿主负责。服务不会签发批准令牌、提供批准界面，也不会自动将预览转为执行。对账调用默认仅生成预览。显式设置 dry_run: false 并提供幂等密钥的调用会存储由服务管理的提案和 Markdown 制品，但绝不会完成对账，也不会更改 Odoo 中的银行对账单行。

配置

本地和 Dedicated Odoo 设置记录在 .env.example 中；Shared Hosted 操作员设置记录在 .env.shared.example 中。不要配置 Odoo 版本：适配器会自动检测版本，并对不受支持或格式错误的响应显式报错。config/config.example.yaml 是安全的 MCP 权限映射示例，并启用当前的读取工具。只有在工具的注册表定义权限下列出了该工具时，该工具才会获得授权；未知或不匹配的条目会阻止启动。

请使用专用的非生产环境 Odoo 技术用户，并仅授予所需的公司和模块访问权限。公司 ID 是额外的 MCP 授权边界，绝不会扩大技术用户在 Odoo 中的权限。

会计工作流

• get_currency_rate_history 返回所选公司的 Odoo 汇率历史，针对一种精确货币，同时保留公司汇率优先于共享汇率的规则，以及两个汇率方向；不会执行货币换算。
• get_trial_balance 返回已过账的期初余额、期间（含首尾日期）的借方和贷方变动、期末余额、合计，以及 Markdown 文件。
• get_profit_and_loss 按 Odoo 的收入和费用科目类型，对期间（含首尾日期）内的已过账分录行进行分类。收入按贷方减借方计算，费用按借方减贷方计算，净利润为收入减费用。
• get_balance_sheet 按 Odoo 的资产、负债和权益科目类型，对截至指定日期（含该日期）的已过账分录行进行分类。它会在权益总额中单独列示未结转收益，并按公司币种精度验证会计等式。
• get_aged_receivables 和 get_aged_payables 按指定日期重建已过账的未结余额，包括之后发生的部分核销，并将其分组到未到期、1–30 天、31–60 天、61–90 天和 90 天以上区间。
• get_cashbook 返回现金和银行日记账中的已过账分录行，以及期初余额、期间借方和贷方、期末余额。
• flag_unmatched_statement_lines 识别尚未核销且在所请求的阈值以上没有唯一合格匹配项的对账单行。
• reconcile_bank_statement_lines 根据金额、合作伙伴、规范化后的参考信息和日期接近程度，为精确的一对一候选项评分。并列项和候选项重复使用都会明确显示为未匹配结果。此工具可以在本地保存建议；它不会执行 Odoo 对账。
• list_open_invoices 和 list_open_bills 按指定日期重建记录币种和公司币种的未结余额，包括之后发生的部分核销。
• create_customer_invoice 和 create_supplier_bill 默认提供只读、不修改数据且仅基于输入的预览。显式执行时会创建一张未过账草稿，并读取 Odoo 实际生效的会计结果。
• create_credit_note 会创建一张关联的完整草稿冲销单。过账前，validate_invoice 会报告本地可判定的余额、币种、科目、总额和税务阻碍，并明确将仅由 Odoo 判定的过账检查留待 Odoo 处理。
• register_payment 将路由发现和执行委托给 Odoo 的标准付款登记向导。预览可能会创建有限数量的临时向导记录，但绝不会执行付款或更改会计记录。对于非手动或无法识别的方式，其可能产生的外部影响会报告为未知。执行需要幂等键以及经过重新验证的最新向导路由。
• list_journal_entries 返回经过筛选的草稿和已过账手动分录，包含有限的分录行详情和不透明的续传游标。create_journal_entry 只会创建借贷平衡的草稿；单独的 post_journal_entry 工具会在显式执行后重新验证并过账一笔现有草稿。

报表结果按确定性顺序排列，并采用游标分页，默认上限为 100 条，最大上限为 500 条。数据为空属于成功的空报表；上游拒绝、超时、数据格式错误或部分获取会作为结构化失败处理，而不会返回空结果。分页后的 Markdown 文件会明确标注行范围、续传状态和整份报表的总计。

损益表和资产负债表中的分析筛选条件会将 Odoo 的百分比分配应用于精确的分析科目 ID。这些报表不会推断自定义会计科目表分组、财年结账规则、合并、抵销或特定本地化的报表布局。遇到不受支持的科目分类时会明确报错，而不会猜测。

薪资证据工作流

• list_payroll_periods 列出公司范围内工资单中观察到的确切日期对，并提供有界的状态、批次和币种证据。
• get_payroll_batch 返回一个确切批次、精简工资单、完整的员工和状态计数，以及按币种划分的观察到的规则／类别合计。
• list_payslips 列出确切批次、确切期间或两者对应的精简工资单事实。get_payslip 返回一份确切工资单，其中包含所有有界的计算行、工作日和一次性输入。
• get_employee_payroll_context 仅返回适用于确切期间的员工和合同／版本证据。
• list_salary_rules 报告符合条件的工资单行中观察到的规则元数据；它不是薪资配置目录。
• get_attendance_summary 按员工、类型、代码和状态汇总薪资工作条目。它不会读取原始考勤数据，也不声称能证明实际出勤。
• compare_payroll_periods 对比两个不重叠期间的确切员工集合、合同事实、工作条目工时，以及按币种划分的观察到的行、规则和类别合计。
• analyze_employee_payroll_change 针对一名确切员工，将直接观察到的变化与相关性及尚未明确的原因区分开来。
• detect_payroll_anomalies 应用固定的公开百分比阈值，以及可选的请求时修正 z 分数检查。它不会学习或保留客户基准；其带有来源链接的 Markdown 摘要会以内联形式返回，不会存储为工件。百分比阈值为 5%（strict）、10%（standard）和 20%（relaxed）。统计检查需要至少六个可比较的历史值，且修正 z 分数的绝对值至少为 3.5；值不足或中位数绝对偏差为零时，会报告为不可用。
• explain_payslip 整理 Odoo 返回的行算术、类别、工作日证据和合同上下文，但不会评估薪资规则代码，也不会复现从税前总额到税后净额的计算。
• prepare_payroll_approval_pack 返回一份请求时生成的 JSON 和内联 Markdown 审核包，其中包含带来源链接的合计、可选的前期差异、异常、例外、限制、建议的人工审核操作和签核清单。它既不会批准薪资，也不会创建持久化的审核包或工作流记录。

这些证据工具需要 payroll_read 权限和可访问的 Odoo 薪资功能。它们均为只读工具，使用请求范围内的分页，返回 Odoo 源 ID，并且仅在审计链中存储非敏感的调用元数据。薪资响应不会作为工件、提案、幂等记录或工作流状态持久化。货币比较绝不会合并或转换币种；已识别的 BASIC、GROSS 和 NET 合计要求使用完全匹配的 Odoo 规则代码，而雇主成本会明确标记为不可用。

受控的薪资草稿写入

• set_draft_payroll_input 可预览，或明确创建或更新一条符合条件的一次性输入，且仅限一份可编辑工资单。
• remove_draft_payroll_input 可预览，或明确移除一条确切且符合条件的一次性输入。
• recalculate_draft_payslip 单独调用 Odoo 的标准工资单计算，并返回最新的工资单证据。

这些工具需要 payroll_draft_write 权限和可访问的 Odoo 薪资功能。每次调用默认只预览，不执行变更。执行需要设置 dry_run: false 并提供非空的幂等键，同时会重新检查完整的当前输入状态，并按工资单串行化写入。输入变更绝不会自动触发重新计算。重新计算仅限可编辑工资单，且不能确认、过账、关闭、支付或以其他方式完成薪资处理。审计和重放仅保留操作 ID 和状态；这些写入工作流不会存储输入描述、金额、员工详细信息或计算所得的薪资值。

验证

运行一条命令，即可在临时目录中执行格式检查、静态分析、测试、软件包构建和构件检查：

uv run python scripts/verify.py

自动化测试使用合成的 Odoo 响应，无法证明与实时 Odoo 版本的兼容性、实际权限、已安装模块或部署网络配置。

存储备份、恢复、完整性验证、监控、升级、回滚和事故处理流程已记录在 docs/operations.md 中。有关安全边界和漏洞报告，请参阅 SECURITY.md；有关受支持的配置和支持请求，请参阅 SUPPORT.md。

docs/demo.md 提供了一个范围明确的会计演示，除非操作员另行授权在非生产 Odoo 环境中执行，否则所有具有写入能力的调用都会保持在预览模式。