Odoo

Interaja com sistemas ERP Odoo, permitindo que assistentes de IA acessem e gerenciem dados de negócios como contatos, vendas e projetos.

Documentação

Servidor MCP para Odoo

CI codecov Ruff Checked with ty Python 3.10+ License: MPL 2.0

Um servidor MCP que permite que assistentes de IA como o Claude interajam com sistemas ERP Odoo. Acesse dados de negócios, pesquise registros, crie novas entradas, atualize dados existentes e gerencie sua instância Odoo por meio de linguagem natural.

Funciona com qualquer instância Odoo! Use o modo YOLO para testes rápidos e demonstrações com qualquer instalação Odoo padrão. Para segurança empresarial, controles de acesso e uso em produção, instale o módulo MCP Odoo.

Recursos

  • 🔍 Pesquise e recupere qualquer registro Odoo (clientes, produtos, faturas, etc.)
  • ✨ Crie novos registros com validação de campos e verificação de permissões
  • ✏️ Atualize dados existentes com tratamento inteligente de campos
  • 🗑️ Exclua registros respeitando permissões de nível de modelo
  • 🔢 Conte registros que correspondam a critérios específicos
  • 📋 Inspecione campos de modelo para entender a estrutura de dados
  • 📊 Agregação no lado do servidor — agrupe, some e conte sem buscar linhas brutas
  • ⚡ Ações de fluxo de trabalho — invoque métodos públicos de negócios (faturar, confirmar pedido de venda, etc.) por meio de uma saída opcional
  • 📎 Recursos binários e de anexos — busque imagens, documentos e arquivos ir.attachment por meio de URIs de recursos
  • 👤 Contexto de sessão personalizado — o usuário conectado, fuso horário e escopo da empresa injetados nas instruções da sessão
  • 🔐 Acesso seguro com chave de API ou autenticação por nome de usuário/senha
  • 🎯 Paginação inteligente para grandes conjuntos de dados
  • 🧠 Seleção inteligente de campos — escolhe automaticamente os campos mais relevantes por modelo
  • 💬 Saída otimizada para LLM com formatação de texto hierárquica
  • 🌍 Suporte a vários idiomas — obtenha respostas no seu idioma preferido
  • 🚀 Modo YOLO para acesso rápido com qualquer instância Odoo (sem necessidade de módulo)

Instalação

Pré-requisitos

  • Python 3.10 ou superior
  • Acesso a uma instância Odoo:
    • Modo padrão (produção): Versão 16.0+ com o módulo MCP Odoo instalado
    • Modo YOLO (testes/demonstrações): Qualquer versão Odoo com XML-RPC habilitado (sem necessidade de módulo)

Instale o UV Primeiro

O servidor MCP é executado no seu computador local (onde o Claude Desktop está instalado), não no seu servidor Odoo. Você precisa instalar o UV na sua máquina local:

macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Após a instalação, reinicie o terminal para garantir que o UV esteja no seu PATH.

Instalação via Configurações MCP (Recomendado)

Adicione esta configuração às suas configurações MCP:

{
  "mcpServers": {
    "odoo": {
      "command": "uvx",
      "args": ["mcp-server-odoo"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_API_KEY": "your-api-key-here"
      }
    }
  }
}
Claude Desktop

Adicione a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "odoo": {
      "command": "uvx",
      "args": ["mcp-server-odoo"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "your-database-name"
      }
    }
  }
}
Claude Code

Adicione a .mcp.json na raiz do seu projeto:

{
  "mcpServers": {
    "odoo": {
      "command": "uvx",
      "args": ["mcp-server-odoo"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "your-database-name"
      }
    }
  }
}

Ou use a CLI:

claude mcp add odoo \
  --env ODOO_URL=https://your-odoo-instance.com \
  --env ODOO_API_KEY=your-api-key-here \
  --env ODOO_DB=your-database-name \
  -- uvx mcp-server-odoo
Cursor

Adicione a ~/.cursor/mcp.json:

{
  "mcpServers": {
    "odoo": {
      "command": "uvx",
      "args": ["mcp-server-odoo"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "your-database-name"
      }
    }
  }
}
VS Code (com GitHub Copilot)

Adicione a .vscode/mcp.json no seu workspace:

{
  "servers": {
    "odoo": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-odoo"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "your-database-name"
      }
    }
  }
}

Nota: O VS Code usa "servers" como chave raiz, não "mcpServers".

Windsurf

Adicione a ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "odoo": {
      "command": "uvx",
      "args": ["mcp-server-odoo"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "your-database-name"
      }
    }
  }
}
Zed

Adicione a ~/.config/zed/settings.json:

{
  "context_servers": {
    "odoo": {
      "command": {
        "path": "uvx",
        "args": ["mcp-server-odoo"],
        "env": {
          "ODOO_URL": "https://your-odoo-instance.com",
          "ODOO_API_KEY": "your-api-key-here",
          "ODOO_DB": "your-database-name"
        }
      }
    }
  }
}

Métodos Alternativos de Instalação

Usando Docker

Execute com Docker — nenhuma instalação Python necessária:

{
  "mcpServers": {
    "odoo": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "ODOO_URL=http://host.docker.internal:8069",
        "-e", "ODOO_API_KEY=your-api-key-here",
        "ivnvxd/mcp-server-odoo"
      ]
    }
  }
}

Nota: Use host.docker.internal em vez de localhost para conectar ao Odoo em execução na máquina host.

Para transporte HTTP:

docker run --rm -p 8000:8000 \
  -e ODOO_URL=http://host.docker.internal:8069 \
  -e ODOO_API_KEY=your-api-key-here \
  ivnvxd/mcp-server-odoo --transport streamable-http --host 0.0.0.0

⚠️ Segurança: o transporte HTTP não possui autenticação integrada — qualquer pessoa que possa alcançar a porta obtém acesso ao Odoo por meio das credenciais do servidor. Publique a porta apenas em redes confiáveis, ou proteja-a com um proxy reverso autenticado. Consulte Opções de Transporte.

A imagem também está disponível no GHCR: ghcr.io/ivnvxd/mcp-server-odoo

Usando pip
# Install globally
pip install mcp-server-odoo

# Or use pipx for isolated environment
pipx install mcp-server-odoo

Em seguida, use mcp-server-odoo como o comando na sua configuração MCP.

A partir do código-fonte
git clone https://github.com/ivnvxd/mcp-server-odoo.git
cd mcp-server-odoo
pip install -e .

Em seguida, use o caminho completo para o pacote na sua configuração MCP.

Configuração

Variáveis de Ambiente

O servidor requer as seguintes variáveis de ambiente:

VariávelObrigatóriaDescriçãoExemplo
ODOO_URLSimURL da sua instância Odoohttps://mycompany.odoo.com
ODOO_API_KEYSim*Chave de API para autenticação0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd
ODOO_USERSim*Nome de usuário (se não estiver usando chave de API)admin
ODOO_PASSWORDSim*Senha (se não estiver usando chave de API)admin
ODOO_DBNãoNome do banco de dados (detectado automaticamente se não definido)mycompany
ODOO_LOCALENãoIdioma/localidade para respostas Odooes_ES, fr_FR, de_DE
ODOO_YOLONãoModo YOLO - ignora a segurança MCP (⚠️ APENAS DEV)off, read, true
ODOO_MCP_ENABLE_METHOD_CALLSNãoHabilita a ferramenta call_model_method — requer ODOO_YOLO=true (⚠️ Perigoso, consulte call_model_method)false, true

*Ou ODOO_API_KEY ou ambos ODOO_USER e ODOO_PASSWORD são obrigatórios. No modo YOLO, ODOO_USER é obrigatório mesmo ao usar uma chave de API.

Notas:

  • Se a listagem de bancos de dados for restrita no seu servidor, você deve especificar ODOO_DB
  • A autenticação por chave de API é recomendada para melhor segurança
  • O servidor também carrega variáveis de ambiente de um arquivo .env no diretório de trabalho

Configuração Avançada

VariávelPadrãoDescrição
ODOO_MCP_DEFAULT_LIMIT10Número padrão de registros retornados por pesquisa
ODOO_MCP_MAX_LIMIT100Limite máximo permitido de registros por solicitação
ODOO_MCP_MAX_SMART_FIELDS15Máximo de campos retornados pela seleção inteligente de campos
ODOO_MCP_LOG_LEVELINFONível de log (DEBUG, INFO, WARNING, ERROR, CRITICAL)
ODOO_MCP_LOG_JSONfalseHabilita saída de log JSON estruturada
ODOO_MCP_LOG_FILE—Caminho para arquivo de log rotativo (10 MB, 5 backups)
ODOO_MCP_LOG_FORMAT—String de formato de log Python personalizada (padrão: %(asctime)s - %(name)s - %(levelname)s - %(message)s)
ODOO_MCP_SLOW_OPERATION_THRESHOLD_MS1000Limite em milissegundos acima do qual uma operação é registrada como lenta
ODOO_MCP_TRANSPORTstdioTipo de transporte (stdio, streamable-http)
ODOO_MCP_HOSTlocalhostHost para vincular no transporte HTTP
ODOO_MCP_PORT8000Porta para vincular no transporte HTTP
ODOO_MCP_ALLOWED_HOSTS—Cabeçalhos Host separados por vírgula para aceitar no transporte HTTP (proteção contra rebinding de DNS). Defina ao executar streamable-http atrás de um proxy reverso que encaminha um host externo, ex.: odoo.example.com,localhost. Literais IPv6 podem estar entre colchetes ou sem ([::1]:8000, ::1). Se não definido, a proteção é habilitada automaticamente apenas para bind de loopback — vincular qualquer outro host (ex.: 0.0.0.0) executa sem validação de Host/Origin.
ODOO_MCP_SESSION_IDLE_TIMEOUT—Segundos de inatividade antes que uma sessão streamable-http seja encerrada e seu estado no lado do servidor seja liberado, ex.: 600. Não definido significa que as sessões nunca expiram.
ODOO_MCP_MAX_BINARY_SIZE52428800Máximo de bytes retornados por um único resources/read binário/anexo. Verificado antes que o payload seja buscado (uma sonda bin_size para campos de registro, o file_size armazenado para anexos), então uma leitura superdimensionada é recusada com um erro limpo em vez de ser puxada para a memória e re-codificada em base64 para o wire.

Opções de Transporte

O servidor suporta múltiplos protocolos de transporte para diferentes casos de uso:

1. stdio (Padrão)

Transporte padrão de entrada/saída — usado por aplicativos de IA de desktop como o Claude Desktop.

# Default transport - no additional configuration needed
uvx mcp-server-odoo

2. streamable-http

Transporte HTTP padrão para acesso no estilo API REST e conectividade remota.

⚠️ Segurança: este transporte não possui autenticação de cliente integrada. Qualquer cliente que possa alcançar a porta pode usar todas as ferramentas e recursos com as credenciais Odoo que o servidor possui — incluindo gravações no modo YOLO de acesso total. Mantenha o bind padrão localhost a menos que a rede seja confiável, e proteja o servidor com um proxy reverso autenticado (ex.: nginx com autenticação básica ou OAuth) para acesso remoto. O servidor registra um aviso ao vincular um host não-loopback.

# Run with HTTP transport (localhost only — safe default)
uvx mcp-server-odoo --transport streamable-http --port 8000

# Binding 0.0.0.0 exposes the server to the network — see the security note above
uvx mcp-server-odoo --transport streamable-http --host 0.0.0.0 --port 8000

# Or use environment variables
export ODOO_MCP_TRANSPORT=streamable-http
export ODOO_MCP_HOST=0.0.0.0
export ODOO_MCP_PORT=8000
uvx mcp-server-odoo

O endpoint HTTP estará disponível em: http://localhost:8000/mcp/

Nota: O transporte SSE (Server-Sent Events) foi descontinuado no protocolo MCP versão 2025-03-26. Use o transporte streamable-http para comunicação baseada em HTTP. Requer biblioteca MCP v1.27.0 ou superior.

Executando transporte streamable-http para acesso remoto
{
  "mcpServers": {
    "odoo-remote": {
      "command": "uvx",
      "args": ["mcp-server-odoo", "--transport", "streamable-http", "--port", "8080"],
      "env": {
        "ODOO_URL": "https://your-odoo-instance.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_DB": "your-database-name"
      }
    }
  }
}

Configurando o Odoo

  1. Instale o módulo MCP:

    • Baixe o módulo mcp_server
    • Instale-o na sua instância Odoo
    • Navegue até Configurações > Servidor MCP
  2. Habilite modelos para acesso MCP:

    • Vá para Configurações > Servidor MCP > Modelos Habilitados
    • Adicione modelos que deseja acessar (ex.: res.partner, product.product)
    • Configure permissões (ler, escrever, criar, excluir) por modelo
  3. Gere uma chave de API:

    • Vá para Configurações > Usuários & Empresas > Usuários
    • Selecione seu usuário
    • Na aba "Chaves de API", crie uma nova chave
    • Copie a chave para sua configuração MCP

Modo YOLO (Desenvolvimento/Testes Apenas) ⚠️

O modo YOLO permite que o servidor MCP se conecte diretamente a qualquer instância Odoo padrão sem exigir o módulo MCP. Este modo ignora todos os controles de segurança MCP e é destinado APENAS para desenvolvimento, testes e demonstrações.

🚨 AVISO: Nunca use o modo YOLO em ambientes de produção!

Níveis do Modo YOLO

  1. Modo Somente Leitura (ODOO_YOLO=read):

    • Permite todas as operações de leitura (pesquisar, ler, contar)
    • Bloqueia todas as operações de escrita (criar, atualizar, excluir)
    • Seguro para demonstrações e testes
    • Mostra indicadores "SOMENTE LEITURA" nas respostas
  2. Modo de Acesso Total (ODOO_YOLO=true):

    • Permite TODAS as operações sem restrições
    • Acesso CRUD completo a todos os modelos
    • EXTREMAMENTE PERIGOSO — use apenas em ambientes isolados
    • Mostra avisos "ACESSO TOTAL" nas respostas

Configuração do Modo YOLO

Modo YOLO Somente Leitura (mais seguro para demonstrações)
{
  "mcpServers": {
    "odoo-demo": {
      "command": "uvx",
      "args": ["mcp-server-odoo"],
      "env": {
        "ODOO_URL": "http://localhost:8069",
        "ODOO_USER": "admin",
        "ODOO_PASSWORD": "admin",
        "ODOO_DB": "demo",
        "ODOO_YOLO": "read"
      }
    }
  }
}
Modo YOLO de Acesso Total (⚠️ use com extrema cautela)
{
  "mcpServers": {
    "odoo-test": {
      "command": "uvx",
      "args": ["mcp-server-odoo"],
      "env": {
        "ODOO_URL": "http://localhost:8069",
        "ODOO_USER": "admin",
        "ODOO_PASSWORD": "admin",
        "ODOO_DB": "test",
        "ODOO_YOLO": "true"
      }
    }
  }
}

Quando Usar o Modo YOLO

✅ Usos Apropriados:

  • Desenvolvimento local com dados de teste
  • Demonstrações rápidas com dados não sensíveis
  • Teste de clientes MCP antes de instalar o módulo MCP
  • Prototipagem em ambientes isolados

❌ Nunca Use Para:

  • Ambientes de produção
  • Instâncias com dados reais de clientes
  • Servidores de desenvolvimento compartilhados
  • Qualquer ambiente com informações sensíveis

Notas de Segurança do Modo YOLO

  • Conecta-se diretamente aos endpoints XML-RPC padrão do Odoo
  • Ignora todos os controles de acesso e restrições de modelo do MCP
  • Nenhuma limitação de taxa é aplicada
  • Todas as operações são registradas, mas não restritas
  • A listagem de modelos mostra 200+ modelos em vez de apenas os habilitados

Exemplos de Uso

Uma vez configurado, você pode pedir ao Claude:

Buscar e Recuperar:

  • "Mostre-me todos os clientes da Espanha"
  • "Encontre produtos com estoque abaixo de 10 unidades"
  • "Liste os pedidos de venda de hoje acima de $1000"
  • "Busque faturas não pagas do mês passado"
  • "Conte quantos funcionários ativos temos"
  • "Mostre-me as informações de contato da Microsoft"

Criar e Gerenciar:

  • "Crie um novo contato de cliente para a Acme Corporation"
  • "Adicione um novo produto chamado 'Premium Widget' com preço $99.99"
  • "Crie um evento de calendário para amanhã às 14h"
  • "Atualize o número de telefone do cliente João da Silva para +1-555-0123"
  • "Altere o status do pedido SO/2024/001 para confirmado"
  • "Exclua o contato de teste que criamos anteriormente"

Ferramentas Disponíveis

search_records

Busque registros em qualquer modelo do Odoo com filtros.

{
  "model": "res.partner",
  "domain": [["is_company", "=", true], ["country_id.code", "=", "ES"]],
  "fields": ["name", "email", "phone"],
  "limit": 10
}

Opções de Seleção de Campos:

  • Omita fields ou defina como null: Retorna seleção inteligente de campos comuns
  • Especifique a lista de campos: Retorna apenas esses campos específicos
  • Uma lista vazia [] é tratada como null (padrões inteligentes)
  • Use ["__all__"]: Retorna todos os campos (use com cautela) — campos semelhantes a credenciais são omitidos e listados no note da resposta; solicite-os explicitamente pelo nome se necessário

get_record

Recupere um registro específico por ID.

{
  "model": "res.partner",
  "record_id": 42,
  "fields": ["name", "email", "street", "city"]
}

Opções de Seleção de Campos:

  • Omita fields ou defina como null: Retorna seleção inteligente de campos comuns com metadados
  • Especifique a lista de campos: Retorna apenas esses campos específicos
  • Uma lista vazia [] é tratada como null (padrões inteligentes)
  • Use ["__all__"]: Retorna todos os campos — campos semelhantes a credenciais são omitidos e indicados nos metadados da resposta; solicite-os explicitamente pelo nome se necessário

As respostas também incluem related_summaries: nomes de exibição para coleções one2many/many2many contendo no máximo 5 IDs, para que relações pequenas sejam legíveis sem consultas adicionais.

get_fields

Descreva os campos de um modelo — tipo, rótulo, obrigatório/somente leitura, destino da relação e opções de seleção. Use para descobrir o esquema de um modelo antes de ler ou escrever registros. Omita attributes para o conjunto padrão selecionado (type, string, required, readonly, relation, selection); uma lista explícita substitui o conjunto selecionado — inclua os padrões na sua lista se ainda precisar deles (ex.: ["type", "string", "help", "store"]). Omita field_names para descrever todos os campos do modelo. Uma lista vazia [] para qualquer parâmetro é tratada como se fosse omitida.

{
  "model": "res.partner",
  "field_names": ["name", "email", "parent_id"]
}

get_current_context

Retorna o contexto da sessão atual: o usuário conectado, seu fuso horário, a empresa ativa e outras empresas permitidas, e orientação sobre manipulação de data/hora UTC. Útil quando não tiver certeza de qual usuário ou empresa executa uma solicitação, ou como interpretar datas e horas. Clientes compatíveis com a especificação também recebem este contexto através das instruções de resposta initialize.

{}

list_models

Liste todos os modelos habilitados para acesso MCP.

{}

list_resource_templates

Liste os modelos de URI de recursos disponíveis e seus padrões.

{}

create_record

Crie um novo registro no Odoo.

{
  "model": "res.partner",
  "values": {
    "name": "New Customer",
    "email": "customer@example.com",
    "is_company": true
  }
}

update_record

Atualize um registro existente.

{
  "model": "res.partner",
  "record_id": 42,
  "values": {
    "phone": "+1234567890",
    "website": "https://example.com"
  }
}

delete_record

Exclua um registro do Odoo.

{
  "model": "res.partner",
  "record_id": 42
}

post_message

Publique uma mensagem no chatter de um registro (mail.thread). subtype="note" (padrão) é um log interno; subtype="comment" notifica seguidores. Defina body_is_html=true para marcação HTML. O subject opcional define uma linha de assunto da mensagem; partner_ids e attachment_ids opcionais referenciam parceiros e anexos existentes.

{
  "model": "res.partner",
  "record_id": 42,
  "body": "Called customer, will follow up Tuesday"
}
{
  "model": "sale.order",
  "record_id": 17,
  "body": "<p>Shipping confirmed for Monday</p>",
  "subtype": "comment",
  "body_is_html": true
}

aggregate_records

Agregação no lado do servidor. Use sempre que a pergunta for "totais/contagens/agrupamentos" em vez de "lista de registros" — isso envia o trabalho para o PostgreSQL em vez de puxar linhas brutas. Despacha para formatted_read_group no Odoo 19+ (o novo método dedicado) e usa read_group com normalização de resposta em versões mais antigas. Os chamadores veem um formato de resposta consistente em todas as versões suportadas. Quando aggregates é omitido, o padrão é ["__count"] para que cada grupo sempre tenha uma contagem. Quando houver mais grupos além da página solicitada, a resposta define has_more: true e um next_hint com o deslocamento de continuação.

{
  "model": "sale.order",
  "groupby": ["date_order:month"],
  "aggregates": ["amount_total:sum"],
  "domain": [["state", "in", ["sale", "done"]]]
}
{
  "model": "res.partner",
  "groupby": ["country_id"]
}

call_model_method

Saída de escape XML-RPC execute_kw genérica — invoca métodos comerciais públicos, para ações de fluxo de trabalho não cobertas por CRUD (faturar, confirmar pedido de venda, validar separação, etc.). Disponível apenas quando tanto ODOO_YOLO=true (YOLO completo) quanto ODOO_MCP_ENABLE_METHOD_CALLS=true estão definidos; caso contrário, a ferramenta não é registrada. Apenas identificadores Python ASCII públicos são aceitos como nomes de métodos — nomes com pontos, hífens, espaços, não ASCII e prefixados com _ são rejeitados.

Algumas chamadas são bloqueadas por segurança mesmo no modo YOLO completo:

  • Modelos ir.actions.* / ir.cron — seus métodos são executados com privilégios elevados (ações de servidor, trabalhos agendados)
  • run / method_direct_trigger em qualquer modelo — mesmo risco de escalonamento via proxies
  • Primitivas ORM de CRUD/acesso a dados (create, write, unlink, read, search*, copy, sudo, ...) — use as ferramentas dedicadas
  • Métodos web_* — a família de acesso a dados do cliente web

Os resultados da lista são truncados em 100 itens.

[!WARNING] Esta ferramenta ainda pode invocar métodos de fluxo de trabalho destrutivos (ex.: button_draft, action_cancel, toggle_active, métodos personalizados). Ative apenas em ambientes confiáveis onde você aceita o raio de impacto. As regras de registro e ACLs do Odoo ainda se aplicam para o usuário autenticado.

{
  "model": "account.move",
  "method": "action_post",
  "arguments": [[42]]
}
{
  "model": "sale.order",
  "method": "action_confirm",
  "arguments": [[7]],
  "keyword_arguments": {"context": {"lang": "en_US"}}
}

Seleção Inteligente de Campos

Quando você omite o parâmetro fields (ou o define como null), o servidor seleciona automaticamente os campos mais relevantes para cada modelo usando um algoritmo de pontuação:

  • Campos essenciais como id, name, display_name e active são sempre incluídos
  • Campos relevantes para negócios (estado, valor, e-mail, telefone, parceiro, etc.) são priorizados
  • Campos técnicos (threads de mensagens, rastreamento de atividades, metadados de site) são excluídos
  • Campos caros (binários, HTML, texto grande) são ignorados; campos computados não armazenados são despriorizados
  • Campos semelhantes a credenciais (nomes terminando em *password, *_pass como smtp_pass, passwd, *secret, *_token, *apikey, ou um composto *_key como api_key/secret_key) são excluídos dos padrões inteligentes e omitidos nas leituras ["__all__"] com uma nota explicativa — solicitar tal campo explicitamente pelo nome ainda o retorna

O limite padrão é de 15 campos por solicitação. As respostas incluem metadados mostrando quais campos foram retornados e quantos campos totais estão disponíveis. Você pode ajustar o limite com ODOO_MCP_MAX_SMART_FIELDS ou ignorá-lo completamente com fields: ["__all__"].

Recursos

O servidor também fornece acesso direto aos dados do Odoo através de URIs de recursos:

Padrão de URIDescrição
odoo://{model}/record/{id}Recupera um registro específico por ID
odoo://{model}/searchBusca registros com configurações padrão (primeiros 10 registros)
odoo://{model}/countConta todos os registros em um modelo
odoo://{model}/fieldsObtém definições de campos e metadados para um modelo
odoo://{model}/record/{id}/{field}Busca um campo binário/imagem de um registro, servido com o mimeType correto
odoo://attachment/{id}Busca um ir.attachment por ID (anexos do tipo URL retornam sua URL como texto)

Exemplos:

  • odoo://res.partner/record/1 — Obtém o parceiro com ID 1
  • odoo://product.product/search — Lista os primeiros 10 produtos
  • odoo://res.partner/count — Conta todos os parceiros
  • odoo://product.product/fields — Mostra todos os campos para produtos
  • odoo://res.partner/record/1/image_128 — Obtém a imagem do avatar do parceiro 1
  • odoo://attachment/42 — Baixa o anexo 42

Campos binários preenchidos nos resultados get_record/search_records são retornados como esses URIs de recursos em vez de base64 inline — leia o URI para recuperar os bytes reais. O conteúdo binário é servido exclusivamente via recursos MCP: os resultados das ferramentas carregam URIs, nunca base64 inline, então seu cliente MCP deve suportar resources/read para buscá-lo.

As leituras de recursos de registro e busca omitem campos semelhantes a credenciais da mesma forma que as leituras em massa das ferramentas — para ler tal campo, solicite-o explicitamente pelo nome através do parâmetro fields das ferramentas.

Leituras binárias e de anexos são servidas inteiras, até ODOO_MCP_MAX_BINARY_SIZE (padrão 50 MB). O tamanho é verificado antes de o payload ser buscado, então um campo ou anexo superdimensionado é recusado com um erro limpo em vez de ser armazenado em buffer em uma resposta correspondentemente grande.

Nota: URIs de recursos não suportam parâmetros de consulta (como ?domain=...). Para filtragem, paginação e seleção de campos, use a ferramenta search_records.

Como Funciona

AI Assistant (Claude, Copilot, etc.)
        ↓ MCP Protocol (stdio or HTTP)
   mcp-server-odoo
        ↓ XML-RPC
   Odoo Instance

O servidor traduz chamadas de ferramentas MCP em solicitações XML-RPC do Odoo. Ele lida com autenticação, controle de acesso, seleção de campos, formatação de dados e tratamento de erros — apresentando dados do Odoo em um formato de texto hierárquico amigável para LLM.

Segurança

  • Sempre use HTTPS em ambientes de produção
  • Mantenha suas chaves de API seguras e rotacione-as regularmente
  • Configure o acesso aos modelos com cuidado — habilite apenas os modelos necessários
  • O módulo MCP respeita os direitos de acesso e regras de registro integrados do Odoo
  • Cada chave de API está vinculada a um usuário específico com suas permissões

Solução de Problemas

Problemas de Conexão

Se você estiver recebendo erros de conexão:

  1. Verifique se sua URL do Odoo está correta e acessível
  2. Confirme que o módulo MCP está instalado: visite https://your-odoo.com/mcp/health
  3. Garanta que seu firewall permita conexões ao Odoo
Erros de Autenticação

Se a autenticação falhar:

  1. Verifique se sua chave de API está ativa no Odoo
  2. Confirme que o usuário tem as permissões apropriadas
  3. Tente regenerar a chave de API
  4. Para autenticação por usuário/senha, garanta que a 2FA não esteja habilitada
Erros de Acesso a Modelos

Se você não conseguir acessar certos modelos:

  1. Vá para Configurações > Servidor MCP > Modelos Habilitados no Odoo
  2. Garanta que o modelo esteja na lista e tenha as permissões apropriadas
  3. Verifique se seu usuário tem acesso a esse modelo nas configurações de segurança do Odoo
Erro "spawn uvx ENOENT"

Este erro significa que o UV não está instalado ou não está no seu PATH:

Solução 1: Instalar UV (veja a seção Instalação acima)

Solução 2: Problema de PATH no macOS O Claude Desktop no macOS não herda o PATH do seu shell. Tente:

  1. Saia completamente do Claude Desktop (Cmd+Q)
  2. Abra o Terminal
  3. Inicie o Claude a partir do Terminal:
    open -a "Claude"
    

Solução 3: Usar Caminho Completo Encontre a localização do UV e use o caminho completo:

which uvx
# Example output: /Users/yourname/.local/bin/uvx

Depois atualize sua configuração:

{
  "command": "/Users/yourname/.local/bin/uvx",
  "args": ["mcp-server-odoo"]
}
Problemas de Configuração do Banco de Dados

Se você vir "Access Denied" ao listar bancos de dados:

  • Isso é normal — algumas instâncias do Odoo restringem a listagem de bancos de dados por segurança
  • Certifique-se de especificar ODOO_DB na sua configuração
  • O servidor usará seu banco de dados especificado sem validação

Exemplo de configuração:

{
  "env": {
    "ODOO_URL": "https://your-odoo.com",
    "ODOO_API_KEY": "your-key",
    "ODOO_DB": "your-database-name"
  }
}

Nota: ODOO_DB é obrigatório se a listagem de bancos de dados for restrita no seu servidor.

Erro "SSL: CERTIFICATE_VERIFY_FAILED"

Este erro ocorre quando o Python não consegue verificar certificados SSL, frequentemente em macOS ou redes corporativas.

Solução: Adicione o caminho do certificado SSL à sua configuração de ambiente:

{
  "env": {
    "ODOO_URL": "https://your-odoo.com",
    "ODOO_API_KEY": "your-key",
    "SSL_CERT_FILE": "/etc/ssl/cert.pem"
  }
}

Isso informa ao Python onde encontrar o pacote de certificados SSL do sistema para conexões HTTPS. O caminho /etc/ssl/cert.pem é o local padrão na maioria dos sistemas.

Modo de Depuração

Ative o registro de depuração para obter mais informações:

{
  "env": {
    "ODOO_URL": "https://your-odoo.com",
    "ODOO_API_KEY": "your-key",
    "ODOO_MCP_LOG_LEVEL": "DEBUG"
  }
}

Desenvolvimento

Executando a partir do código-fonte
# Clone the repository
git clone https://github.com/ivnvxd/mcp-server-odoo.git
cd mcp-server-odoo

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest --cov

# Run the server
python -m mcp_server_odoo

# Check version
python -m mcp_server_odoo --version
Testando com o MCP Inspector
# Using uvx
npx @modelcontextprotocol/inspector uvx mcp-server-odoo

# Using local installation
npx @modelcontextprotocol/inspector python -m mcp_server_odoo

Testes

Executando Testes

# Unit tests (no Odoo needed)
uv run pytest -m "not yolo and not mcp" --cov

# YOLO integration tests (vanilla Odoo, no MCP module)
uv run pytest -m "yolo" -v

# MCP integration tests (Odoo + MCP module installed)
uv run pytest -m "mcp" -v

# All tests
uv run pytest --cov

# Run specific test categories
uv run pytest tests/test_tools.py -v
uv run pytest tests/test_server_foundation.py -v

Licença

Este projeto está licenciado sob a Mozilla Public License 2.0 (MPL-2.0) - consulte o arquivo LICENSE para detalhes.

Contribuindo

Contribuições são muito bem-vindas! Consulte o guia CONTRIBUTING para detalhes.

Suporte

Obrigado por usar este projeto! Se você o achar útil e quiser apoiar meu trabalho, considere me pagar um café. Seu apoio é muito apreciado!

Buy Me A Coffee

E não se esqueça de dar uma estrela ao projeto se você gostou! :star: