Odoo MCP

Odoo MCP

odoo-mcp é um servidor MCP nativo de fluxo de trabalho para Odoo Enterprise. Ele expõe descoberta de capacidades somente leitura, relatórios de balancete, relatórios de contas a receber e a pagar por idade, visibilidade de livro-caixa, detecção de linhas bancárias não conciliadas e conciliação bancária somente com proposta.

A versão inicial de contabilidade também suporta fluxos de trabalho limitados de fatura, fatura de fornecedor, nota de crédito, registro de pagamento e lançamento manual. Ferramentas de mutação são somente pré-visualização por padrão e exigem execução explícita além de idempotência.

O adaptador contábil interno fornece primitivas de leitura limitadas, tipadas e com escopo por empresa para os fluxos de trabalho de relatórios. Ele impõe listas de permissão fixas de modelos/ações, remove campos negados, normaliza datas, decimais, relações e páginas de cursor, e traduz falhas de autenticação, permissão e transporte do Odoo em erros seguros. Ele não expõe CRUD genérico nem uma superfície de configuração do Odoo.

Destinos de conexão suportados são Odoo.sh e Odoo Enterprise auto-hospedado:

• Odoo 18 via JSON-RPC externo
• Odoo 19 via JSON-2

Outras versões do Odoo, Odoo Online, edição Community e forks personalizados não são suportados. Este pacote não é um módulo do Odoo e não expõe CRUD genérico de modelos.

Instalação

O produto e os comandos são nomeados odoo-mcp; a distribuição PyPI é odoo-erp-mcp porque o nome da distribuição odoo-mcp pertence a outro projeto.

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

O pacote também expõe odoo-erp-mcp como um inicializador de compatibilidade para clientes do MCP Registry. Ele inicia o mesmo servidor que odoo-mcp.

Desenvolvimento Local

Requer Python 3.11 ou mais recente e 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

O Desenvolvimento Local usa stdio. As configurações de ambiente do processo têm precedência sobre .env.local. Nunca faça commit de .env.local.

Perfis remotos

Dedicado Remoto e Hospedado Compartilhado usam o mesmo servidor, registro, fluxo de trabalho e adaptador Odoo que o Desenvolvimento Local, expostos via HTTP Streamable:

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

O Dedicado Remoto lê sua única conexão Odoo do ambiente do processo; ele nunca carrega .env.local. Cada solicitação /mcp deve conter um JWT HS256 de portador emitido pela implantação. O servidor valida sua assinatura, emissor fixo, público fixo, expiração, horário de emissão, assunto e ID do cliente antes do roteamento MCP; permissões e concessões de empresa permanecem de propriedade do servidor. Configure ODOO_MCP_AUTH_ISSUER, ODOO_MCP_AUTH_AUDIENCE e um ODOO_MCP_AUTH_SIGNING_KEY fornecido pelo cofre de segredos com pelo menos 32 caracteres.

Hospedado Compartilhado é um aplicativo executável de inscrição aberta na mesma imagem. Ele atende descoberta OAuth, registro dinâmico de clientes, autorização, token, revogação, inscrição por navegador, metadados de recursos protegidos e rotas MCP. O aplicativo verifica cada conexão Odoo, permite que o usuário selecione entre as empresas que o Odoo retornou, armazena a credencial criptografada e vincula cada token a exatamente um conector ativo. Configure-o a partir de .env.shared.example; suas chaves de criptografia de 256 bits com versão devem vir de um cofre de segredos controlado pelo operador. Configuração ausente, texto cifrado inválido, concessões inativas, destinos Odoo inseguros e vínculos de conector não autorizados falham de forma segura. O Hospedado Compartilhado suporta um processo gravável com um volume SQLite local durável ou PostgreSQL qualificado com runtime em pool e conexões de migração diretas. TLS, ingresso público, monitoramento e implantação de produção permanecem responsabilidades do operador.

Modelos reproduzíveis de Docker e systemd para Dedicado Remoto, requisitos de integração do Hospedado Compartilhado e orientações de endurecimento de rede estão em docs/deployment.md. Não exponha o ouvinte HTTP de exemplo diretamente à internet pública.

Estado durável

odoo_mcp.storage.Storage fornece migrações ordenadas de SQLite e PostgreSQL e repositórios com escopo por inquilino para registros de auditoria, propostas, artefatos, reservas de idempotência, instantâneos de capacidade e conexões criptografadas do Hospedado Compartilhado. Linhas de auditoria são somente anexação e encadeadas por hash SHA-256 por inquilino. Reservas de idempotência vinculam o inquilino, empresa, ferramenta, chave e carga útil da solicitação para reprodução por 24 horas, enquanto resultados em andamento e desconhecidos permanecem bloqueados para recuperação explícita. Resultados finais devem reter uma resposta reproduzível e corresponder à empresa reservante. O texto de falha de auditoria é derivado de códigos de erro registrados; texto de erro de upstream de forma livre não é persistido.

Backups do SQLite usam um instantâneo consistente. A restauração grava em um novo destino e é aceita somente após verificação de integridade do banco de dados, migrações, cadeias de auditoria do inquilino, estado de idempotência, dados de capacidade e conexões criptografadas. Chaves de criptografia devem ser copiadas e restauradas separadamente. O PostgreSQL usa serialização de migração no nível do banco de dados e preserva os mesmos contratos de repositório, OAuth, auditoria, idempotência, criptografia e ciclo de vida.

O servidor armazena estado durável local em .odoo-mcp/state.sqlite3 por padrão. Use --storage <path> para selecionar um arquivo SQLite diferente. Relatórios contábeis bem-sucedidos persistem atomicamente seu artefato Markdown e um resultado de auditoria compacto; chamadas de relatório com falha e negadas persistem uma auditoria de falha segura para segredos quando uma identidade de isolamento foi resolvida.

Segurança de gravação

odoo_mcp.policy.WriteSafetyCoordinator é o limite obrigatório para fluxos de trabalho com capacidade de gravação. Ele impõe metadados de risco do registro, identidade resolvida, permissão, empresa e portões de capacidade antes da preparação do fluxo de trabalho. Chamadas padrão para comportamento somente pré-visualização. A execução requer dry_run: false explícito e uma chave de idempotência não vazia, então reserva essa chave e anexa a auditoria de tentativa antes da validação de estado atualizado e da mutação do Odoo.

Resultados bem-sucedidos, rejeitados, conflitantes, reproduzidos, com falha conhecida e desconhecidos permanecem distintos e seguros para reprodução após reinicialização. Uma mutação incerta nunca é repetida automaticamente; se a persistência do resultado falhar após uma possível mutação, a reserva em andamento continua bloqueando a execução duplicada. Negativas de permissão do Odoo que comprovam que nenhuma mutação ocorreu permanecem falhas conhecidas estruturadas. Texto de auditoria e resposta suprimem detalhes brutos de exceção.

A confirmação humana pertence ao host do cliente MCP. O servidor não emite tokens de aprovação, fornece uma interface de aprovação ou transforma automaticamente uma pré-visualização em execução. Chamadas de conciliação padrão para pré-visualização. Uma chamada explícita dry_run: false com uma chave de idempotência armazena uma proposta de propriedade do servidor e artefato Markdown, mas nunca finaliza a conciliação nem altera uma linha de extrato bancário no Odoo.

Configuração

As configurações do Odoo Local e Dedicado estão documentadas em .env.example; as configurações do operador do Hospedado Compartilhado estão documentadas em .env.shared.example. Não configure uma versão do Odoo: o adaptador a detecta e falha explicitamente para respostas não suportadas ou malformadas. config/config.example.yaml é o exemplo seguro de mapa de permissões MCP e habilita as ferramentas de leitura atuais. Uma ferramenta é autorizada somente quando listada sob sua permissão definida no registro; entradas desconhecidas ou incompatíveis impedem a inicialização.

Use um usuário técnico Odoo dedicado de não produção com apenas o acesso de empresa e módulo necessário. IDs de empresa são um limite adicional de autorização MCP e nunca expandem as permissões do usuário técnico no Odoo.

Fluxos de trabalho contábeis

• get_trial_balance retorna saldos iniciais lançados, movimento de débito e crédito do período inclusivo, saldos finais, totais e um artefato Markdown.
• get_profit_and_loss classifica linhas lançadas pelos tipos de conta de receita e despesa do Odoo para um período inclusivo. Receita usa crédito menos débito, despesas usam débito menos crédito, e lucro líquido é receita menos despesas.
• get_balance_sheet classifica linhas lançadas pelos tipos de conta de ativo, passivo e patrimônio líquido do Odoo até uma data inclusiva. Ele relata lucros não encerrados separadamente dentro do patrimônio líquido total e verifica a equação contábil na precisão da moeda da empresa.
• get_aged_receivables e get_aged_payables reconstroem resíduos lançados até uma data, incluindo conciliações parciais posteriores, e os agrupam em buckets de não vencidos, 1–30, 31–60, 61–90 e 90+ dias.
• get_cashbook retorna linhas de lançamento lançadas de diários de caixa e banco com saldo inicial, débito e crédito do período e saldo final.
• flag_unmatched_statement_lines identifica linhas de extrato não conciliadas sem uma correspondência elegível única no limite solicitado ou acima dele.
• reconcile_bank_statement_lines pontua candidatos exatos um-para-um por valor, parceiro, referência normalizada e proximidade de data. Empates e reutilização de candidatos permanecem resultados explícitos sem correspondência. A ferramenta pode persistir uma proposta localmente; ela não realiza conciliação no Odoo.
• list_open_invoices e list_open_bills reconstroem resíduos em moeda de registro e de empresa até uma data, incluindo conciliações parciais posteriores.
• create_customer_invoice e create_supplier_bill fornecem pré-visualizações não mutáveis, somente de entrada por padrão. A execução explícita cria um rascunho não lançado e lê de volta os resultados contábeis efetivos do Odoo.
• create_credit_note cria uma reversão completa de rascunho vinculada. Antes do lançamento, validate_invoice relata bloqueadores de saldo, moeda, conta, total e impostos determináveis localmente, enquanto adia explicitamente verificações de lançamento somente do Odoo.
• register_payment delega descoberta de rota e execução ao assistente padrão de registro de pagamento do Odoo. A pré-visualização pode criar registros de assistente efêmeros limitados, mas nunca executa um pagamento nem altera registros contábeis. Métodos não manuais ou não identificados relatam seu possível efeito externo como desconhecido. A execução requer uma chave de idempotência e uma rota de assistente revalidada recentemente.
• list_journal_entries retorna lançamentos manuais filtrados, lançados e em rascunho, com detalhes de linha limitados e cursores de continuação opacos. create_journal_entry cria apenas um rascunho equilibrado, enquanto a ferramenta separada post_journal_entry revalida e lança um rascunho existente após execução explícita.

Os resultados dos relatórios são ordenados deterministicamente e paginados por cursor com um limite padrão de 100 e máximo de 500. Dados vazios são um relatório vazio bem-sucedido; negação de upstream, tempo limite, dados malformados ou recuperação parcial são uma falha estruturada em vez de um resultado vazio. Artefatos Markdown paginados rotulam o intervalo de linhas, estado de continuação e totais do relatório inteiro explicitamente.

Filtros analíticos de lucros e perdas e balanço patrimonial aplicam a distribuição percentual do Odoo a IDs exatos de contas analíticas. Esses relatórios não inferem grupos personalizados de plano de contas, regras de encerramento de exercício fiscal, consolidação, eliminações ou layouts de relatórios específicos de localização. Classificações de contas não suportadas falham explicitamente em vez de serem adivinhadas.

Verificação

Um comando executa verificações de formatação, análise estática, testes, builds de pacotes e inspeção de artefatos em diretórios temporários:

uv run python scripts/verify.py

Testes automatizados usam respostas Odoo sintéticas. Eles não estabelecem compatibilidade ao vivo com versões do Odoo, permissões reais, módulos instalados ou rede de implantação.

Procedimentos de backup de armazenamento, restauração, verificação de integridade, monitoramento, atualização, reversão e incidentes estão documentados em docs/operations.md. Veja SECURITY.md para o limite de segurança e relato de vulnerabilidades, e SUPPORT.md para configurações suportadas e solicitações de suporte.

docs/demo.md fornece uma demonstração contábil limitada que mantém toda chamada com capacidade de gravação em modo de pré-visualização, a menos que o operador autorize separadamente a execução em um ambiente Odoo de não produção.