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
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.attachmentpor 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.internalem vez delocalhostpara 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ável | Obrigatória | Descrição | Exemplo |
|---|---|---|---|
ODOO_URL | Sim | URL da sua instância Odoo | https://mycompany.odoo.com |
ODOO_API_KEY | Sim* | Chave de API para autenticação | 0ef5b399e9ee9c11b053dfb6eeba8de473c29fcd |
ODOO_USER | Sim* | Nome de usuário (se não estiver usando chave de API) | admin |
ODOO_PASSWORD | Sim* | Senha (se não estiver usando chave de API) | admin |
ODOO_DB | Não | Nome do banco de dados (detectado automaticamente se não definido) | mycompany |
ODOO_LOCALE | Não | Idioma/localidade para respostas Odoo | es_ES, fr_FR, de_DE |
ODOO_YOLO | Não | Modo YOLO - ignora a segurança MCP (⚠️ APENAS DEV) | off, read, true |
ODOO_MCP_ENABLE_METHOD_CALLS | Não | Habilita 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
.envno diretório de trabalho
Configuração Avançada
| Variável | Padrão | Descrição |
|---|---|---|
ODOO_MCP_DEFAULT_LIMIT | 10 | Número padrão de registros retornados por pesquisa |
ODOO_MCP_MAX_LIMIT | 100 | Limite máximo permitido de registros por solicitação |
ODOO_MCP_MAX_SMART_FIELDS | 15 | Máximo de campos retornados pela seleção inteligente de campos |
ODOO_MCP_LOG_LEVEL | INFO | Nível de log (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
ODOO_MCP_LOG_JSON | false | Habilita 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_MS | 1000 | Limite em milissegundos acima do qual uma operação é registrada como lenta |
ODOO_MCP_TRANSPORT | stdio | Tipo de transporte (stdio, streamable-http) |
ODOO_MCP_HOST | localhost | Host para vincular no transporte HTTP |
ODOO_MCP_PORT | 8000 | Porta 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_SIZE | 52428800 | Má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
localhosta 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
-
Instale o módulo MCP:
- Baixe o módulo mcp_server
- Instale-o na sua instância Odoo
- Navegue até Configurações > Servidor MCP
-
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
-
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
-
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
-
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
fieldsou defina comonull: Retorna seleção inteligente de campos comuns - Especifique a lista de campos: Retorna apenas esses campos específicos
- Uma lista vazia
[]é tratada comonull(padrões inteligentes) - Use
["__all__"]: Retorna todos os campos (use com cautela) — campos semelhantes a credenciais são omitidos e listados nonoteda 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
fieldsou defina comonull: Retorna seleção inteligente de campos comuns com metadados - Especifique a lista de campos: Retorna apenas esses campos específicos
- Uma lista vazia
[]é tratada comonull(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_triggerem 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_nameeactivesã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,*_passcomosmtp_pass,passwd,*secret,*_token,*apikey, ou um composto*_keycomoapi_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 URI | Descrição |
|---|---|
odoo://{model}/record/{id} | Recupera um registro específico por ID |
odoo://{model}/search | Busca registros com configurações padrão (primeiros 10 registros) |
odoo://{model}/count | Conta todos os registros em um modelo |
odoo://{model}/fields | Obté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 1odoo://product.product/search— Lista os primeiros 10 produtosodoo://res.partner/count— Conta todos os parceirosodoo://product.product/fields— Mostra todos os campos para produtosodoo://res.partner/record/1/image_128— Obtém a imagem do avatar do parceiro 1odoo://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 ferramentasearch_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:
- Verifique se sua URL do Odoo está correta e acessível
- Confirme que o módulo MCP está instalado: visite
https://your-odoo.com/mcp/health - Garanta que seu firewall permita conexões ao Odoo
Erros de Autenticação
Se a autenticação falhar:
- Verifique se sua chave de API está ativa no Odoo
- Confirme que o usuário tem as permissões apropriadas
- Tente regenerar a chave de API
- 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:
- Vá para Configurações > Servidor MCP > Modelos Habilitados no Odoo
- Garanta que o modelo esteja na lista e tenha as permissões apropriadas
- 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:
- Saia completamente do Claude Desktop (Cmd+Q)
- Abra o Terminal
- 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_DBna 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!
E não se esqueça de dar uma estrela ao projeto se você gostou! :star:
