Odoo MCP Server (OdooConsole)

Odoo MCP Server

Um servidor MCP (Model Context Protocol) que conecta agentes de IA a instâncias ERP Odoo. Funciona com Claude Code, Cursor, Windsurf e qualquer cliente compatível com MCP.

Suporta Odoo 17-18 (JSON-RPC) e Odoo 19+ (JSON-2 API) — detecta automaticamente o melhor protocolo.

Início Rápido

# Run directly (uv handles dependencies automatically)
ODOO_URL=https://my.odoo.com ODOO_DB=mydb ODOO_USER=admin ODOO_PASSWORD=secret \
  uv run odoo_mcp_server.py

Nenhum virtualenv ou pip install necessário — o script tem metadados inline que uv resolve automaticamente.

Configurar no Claude Code

Adicione ao .mcp.json do seu projeto:

{
  "mcpServers": {
    "odoo": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--python", "3.11", "--script", "/path/to/odoo_mcp_server.py"],
      "env": {
        "ODOO_URL": "https://your-instance.odoo.com",
        "ODOO_DB": "your-database",
        "ODOO_USER": "admin",
        "ODOO_PASSWORD": "your-password"
      }
    }
  }
}

Ou para Odoo 19+ com autenticação por chave de API:

{
  "mcpServers": {
    "odoo": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--python", "3.11", "--script", "/path/to/odoo_mcp_server.py"],
      "env": {
        "ODOO_URL": "https://your-instance.odoo.com",
        "ODOO_DB": "your-database",
        "ODOO_USER": "admin",
        "ODOO_API_KEY": "your-api-key"
      }
    }
  }
}

Configurar no Cursor / Windsurf

Adicione a ~/.cursor/mcp.json ou equivalente:

{
  "mcpServers": {
    "odoo": {
      "command": "uv",
      "args": ["run", "--python", "3.11", "--script", "/path/to/odoo_mcp_server.py"],
      "env": {
        "ODOO_URL": "https://your-instance.odoo.com",
        "ODOO_DB": "your-database",
        "ODOO_USER": "admin",
        "ODOO_PASSWORD": "your-password"
      }
    }
  }
}

Variáveis de Ambiente

Variável	Obrigatório	Descrição
ODOO_URL	Sim	URL da instância Odoo
ODOO_DB	Sim	Nome do banco de dados
ODOO_USER	Sim	Nome de usuário de login
ODOO_PASSWORD	Um destes	Senha (Odoo 17-18)
ODOO_API_KEY	obrigatório	Chave de API (Odoo 19+, preferida)
ODOO_READONLY	Não	Defina como true para desativar todas as operações de escrita

Modo Somente Leitura

Defina ODOO_READONLY=true para desativar as ferramentas create, update, delete e execute. Útil para navegação segura em instâncias de produção:

{
  "mcpServers": {
    "odoo": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--python", "3.11", "--script", "/path/to/odoo_mcp_server.py"],
      "env": {
        "ODOO_URL": "https://production.odoo.com",
        "ODOO_DB": "prod",
        "ODOO_USER": "readonly-user",
        "ODOO_PASSWORD": "secret",
        "ODOO_READONLY": "true"
      }
    }
  }
}

Ferramentas Disponíveis

CRUD Principal

Ferramenta	Descrição
odoo_search_read	Consultar registros com filtros de domínio, seleção de campos, paginação
odoo_search_count	Contar registros correspondentes sem buscar dados
odoo_export	Exportação em massa de até 2000 registros por chamada para planilhas
odoo_create	Criar novos registros
odoo_update	Atualizar registros existentes por ID
odoo_delete	Excluir registros por ID
odoo_execute	Executar qualquer método de modelo (action_confirm, action_post, etc.)

Descoberta

Ferramenta	Descrição
odoo_list_models	Descobrir modelos disponíveis com filtro de palavra-chave
odoo_get_fields	Inspecionar definições de campos para qualquer modelo
odoo_doctor	Diagnósticos de saúde (versão, módulos, usuários, crons, erros)
odoo_connection_info	Mostrar detalhes da conexão atual

Personalização de Modelos

Ferramenta	Descrição
odoo_model_info	Obter metadados abrangentes do modelo em uma única chamada — campos, visualizações, ações, padrões, ordem de classificação
odoo_set_default	Definir, atualizar ou limpar o valor padrão de um campo (lida com ir.default + codificação JSON)
odoo_get_view	Obter o XML da visualização de formulário/árvore/pesquisa totalmente renderizado (mesclado)
odoo_modify_action	Alterar o domínio, contexto, ordem de classificação, limite ou modos de visualização de uma ação de janela

Exemplo de Uso

Depois de configurado, pergunte ao seu agente de IA:

• "Listar todos os pedidos de venda deste mês"
• "Mostre-me os campos em res.partner"
• "Criar um novo contato chamado Acme Corp"
• "Executar uma verificação de saúde na instância Odoo"
• "Exportar todos os produtos para uma planilha"
• "Confirmar pedido de venda 42"

Exemplos de Personalização de Modelos

• "Qual é a ordem de classificação padrão para sale.order?"
• "Alterar a política de faturamento padrão em produtos para 'delivery'"
• "Mostre-me a visualização de formulário para res.partner"
• "Quais ações de janela existem para account.move? Alterar a classificação padrão para data desc"
• "Listar todos os campos personalizados em res.partner"
• "Quais campos são obrigatórios em sale.order?"

Ferramentas de Personalização de Modelos — Referência Detalhada

odoo_model_info

Retorna tudo sobre um modelo em uma única chamada, eliminando a necessidade de múltiplas consultas exploratórias.

odoo_model_info(model="sale.order")

Retorna:

• default_order — o atributo _order do modelo (ex.: "date_order desc, id desc")
• rec_name — o campo usado para nome de exibição em menus suspensos
• field_count — número total de campos
• fields_by_type — contagem de campos agrupados por tipo (many2one: 12, char: 8, ...)
• custom_fields — campos criados pelo usuário (prefixo x_ ou state=manual)
• relational_fields — todos os Many2one, One2many, Many2many com seus alvos
• required_fields — campos que devem ser preenchidos
• views — visualizações base (formulário, árvore, pesquisa) com IDs e prioridades
• actions — ações de janela com seu domínio, contexto e modos de visualização
• defaults — valores ir.default atuais definidos para os campos deste modelo

odoo_set_default

Gerencia padrões de campo via ir.default com codificação JSON adequada. A fonte mais comum de erros de agente quando feito manualmente.

# Set global default
odoo_set_default(model="product.template", field_name="invoice_policy", value="delivery")

# Set user-specific default
odoo_set_default(model="sale.order", field_name="warehouse_id", value=2, user_id=5)

# Remove a default
odoo_set_default(model="product.template", field_name="invoice_policy", value=null)

A ferramenta:

1. Encontra o field_id em ir.model.fields (valida se o campo existe)
2. Codifica o valor em JSON automaticamente
3. Cria ou atualiza o registro ir.default
4. Retorna valores antes/depois para confirmação

odoo_get_view

Retorna o XML da visualização totalmente renderizado após toda a herança ser aplicada — o que o usuário realmente vê, não os fragmentos brutos armazenados em ir.ui.view.

odoo_get_view(model="sale.order", view_type="form")
odoo_get_view(model="res.partner", view_type="tree")
odoo_get_view(model="account.move", view_type="search")

Retorna:

• arch — o XML mesclado completo
• view_id — o ID da visualização base
• fields_in_view — lista de nomes de campos presentes na visualização

odoo_modify_action

Altera como um modelo aparece na interface do usuário modificando sua ação de janela (ir.actions.act_window).

# List actions for a model (read-only)
odoo_modify_action(model="sale.order")

# Change default sort order
odoo_modify_action(action_id=42, order="date_order desc")

# Change default filter and page size
odoo_modify_action(action_id=42, domain="[['state','=','sale']]", limit=200)

# Add default grouping via context
odoo_modify_action(action_id=42, context="{'group_by': 'partner_id'}")

A ferramenta retorna valores antes/depois para que você possa verificar o que mudou.

Como Funciona

AI Agent (Claude, Cursor, etc.)
    ↕ MCP Protocol (stdio)
Odoo MCP Server
    ↕ JSON-RPC / JSON-2 API
Odoo Instance

O servidor autentica uma vez na inicialização e mantém uma conexão persistente. Todas as ferramentas usam a mesma sessão autenticada.

Requisitos

• Python 3.11+
• uv (recomendado) ou pip install fastmcp httpx

Licença

MIT