Servidor MCP para Odoo 19 (API JSON-2)

odoo19-mcp-server MCP server

License: Apache-2.0 Python GitHub stars GitHub last commit Awesome MCP Servers

Tutorial en Youtube - ¡Crea tu propio servidor MCP! Tutorial completo de Odoo 19 + FastMCP

Servidor MCP para Odoo 19, utilizando la conexión API JSON-2.

Este proyecto está desarrollado basándose en la Guía completa de uso de la API JSON-2 de Odoo 19.

Captura de pantalla de ejecución

Stack tecnológico

Python: 3.13
FastMCP: >=3.0.0,<4.0.0
odoo-client-lib: 2.0.1 (API JSON-2)

Arquitectura

flowchart TB
    subgraph Client["MCP Client"]
        CC[Claude Code]
        GC[Gemini CLI]
        MI[MCP Inspector]
    end

    subgraph Server["MCP Server (FastMCP)"]
        R[Resources<br/>odoo://models<br/>odoo://user<br/>odoo://company]
        T[Tools<br/>search_records<br/>create_record<br/>update_record]
        DI[Dependency Injection<br/>get_shared_client]
    end

    subgraph RPC["OdooJsonRpcClient"]
        OL[odoolib<br/>json2/json2s protocol]
    end

    subgraph Odoo["Odoo Server"]
        EP["/jsonrpc endpoint"]
    end

    Client -->|MCP Protocol<br/>stdio/http/sse| Server
    R --> DI
    T --> DI
    DI --> RPC
    RPC -->|HTTP/HTTPS| Odoo

Conceptos clave de MCP

Recursos vs Herramientas

Característica	Recursos	Herramientas
Propósito	Proporcionar información de contexto	Ejecutar operaciones/acciones
Activación	Controlado por el cliente (ej. Claude Code)	El LLM decide automáticamente cuándo llamar
Parámetros	Ninguno (o parámetros URI)	Sí (requiere generación por el LLM)
Analogía	Manual del empleado (conocimiento previo)	Caja de herramientas (uso bajo demanda)
Analogía HTTP	GET (lectura)	POST/PUT/DELETE (operación)

Recursos - Contexto dinámico, información de fondo que el LLM conoce desde el principio:

odoo://user     → "我是誰"
odoo://company  → "我在哪間公司"
odoo://models   → "有哪些模型可用"

Herramientas - Operaciones que solo se llaman cuando es necesario:

search_records(model="res.partner", domain=[...])  → 搜尋
create_record(model="sale.order", values={...})    → 建立

¿Por qué no usar un Prompt predeterminado?

Método	Prompt predeterminado	Recurso
Fuente de datos	Codificado en el programa	Consulta en tiempo real a Odoo
Momento de actualización	Durante el despliegue	En cada conexión
Cambio de usuario	Información incorrecta	Automáticamente correcto

# ❌ Default Prompt（寫死）
SYSTEM_PROMPT = "當前用戶: Admin"  # 換人登入就錯了

# ✅ Resource（動態）
@mcp.resource("odoo://user")
def get_current_user():
    return client.read("res.users", [uid])  # 即時查詢

Conclusión: El recurso es un "contexto dinámico", no texto estático.

Referencia: Recursos MCP | Herramientas MCP

Variables de entorno

Variable	Descripción	Valor predeterminado
`ODOO_URL`	URL del servidor Odoo	`http://localhost:8069`
`ODOO_DATABASE`	Nombre de la base de datos	-
`ODOO_API_KEY`	Autenticación con API Key	-
`READONLY_MODE`	Modo de solo lectura (prohíbe operaciones de escritura)	`false`

Crea un archivo .env:

cp .env.example .env

Instalación

pip install -r requirements.txt

Cómo iniciar

Modo de desarrollo (MCP Inspector)

fastmcp dev inspector odoo_mcp_server.py

Modos de transporte (Transport)

Este proyecto soporta tres modos de transporte MCP:

Modo	Descripción	Escenario de aplicación
`stdio`	Entrada/salida estándar (predeterminado)	Claude Desktop, Cursor IDE, desarrollo local
`http`	Protocolo HTTP	Servicios remotos, n8n, integración de aplicaciones web
`sse`	Server-Sent Events (obsoleto)	Compatibilidad con clientes antiguos

stdio vs HTTP/SSE: Ubicación de la potencia de cálculo

La diferencia clave entre ambos modos radica en "quién inicia el servidor MCP" y "dónde se ejecuta la potencia de cálculo":

Modo stdio (potencia de cálculo local)

┌─────────────────────────────────────┐
│            你的電腦 💻               │
│                                     │
│  Claude Desktop ──> MCP Server      │
│                     (使用本機算力)   │
└─────────────────────────────────────┘

El cliente (ej. Claude Desktop) inicia el servidor MCP como un subproceso
El servidor MCP utiliza la CPU/RAM de tu computadora
El servidor se inicia/cierra junto con el cliente

Modo HTTP/SSE (potencia de cálculo remota)

┌──────────────┐         ┌──────────────────┐
│   你的電腦    │         │     雲端 ☁️       │
│              │         │                  │
│Claude Desktop│ ──網路──>│   MCP Server     │
│  (輕量)      │         │  (使用雲端算力)   │
└──────────────┘         └──────────────────┘

El servidor MCP se ejecuta de forma independiente en la nube/host remoto
Múltiples clientes pueden conectarse al mismo servidor simultáneamente
Adecuado para uso compartido en equipo, integración con n8n, entorno de producción

Iniciar diferentes modos

# stdio 模式（預設）
python odoo_mcp_server.py

# HTTP 模式
python odoo_mcp_server.py --transport http --host 0.0.0.0 --port 8000

# SSE 模式（已棄用，建議使用 HTTP）
python odoo_mcp_server.py --transport sse --host 0.0.0.0 --port 8000

Despliegue en la nube (modo HTTP)

Ejemplo de Docker Compose:

services:
  odoo-mcp:
    build: .
    ports:
      - "8000:8000"
    environment:
      - ODOO_URL=http://odoo:8069
      - ODOO_DATABASE=odoo19
      - ODOO_API_KEY=your_api_key_here
    command: ["python", "odoo_mcp_server.py", "--transport", "http", "--host", "0.0.0.0", "--port", "8000"]
    restart: unless-stopped

Configuración del cliente (claude) para usar conexión por URL:

claude mcp add --transport http odoo-mcp https://your-cloud-server.com:8000/mcp

{
  "mcpServers": {
    "odoo-mcp": {
      "type": "http",
      "url": "https://your-cloud-server.com:8000/mcp"
    }
  }
}

Recursos MCP

URI	Descripción
`odoo://models`	Listar todos los modelos
`odoo://model/{model_name}`	Obtener definición de campos del modelo
`odoo://record/{model_name}/{record_id}`	Obtener un registro individual
`odoo://user`	Información del usuario conectado actualmente
`odoo://company`	Información de la empresa del usuario actual

Herramientas MCP

Herramienta	Descripción	Solo lectura
`list_models`	Listar/buscar modelos disponibles	Sí
`get_fields`	Obtener definición de campos del modelo	Sí
`search_records`	Buscar registros	Sí
`count_records`	Contar registros	Sí
`read_records`	Leer registro por ID	Sí
`create_record`	Crear registro	No
`update_record`	Actualizar registro	No
`delete_record`	Eliminar registro (requiere doble confirmación)	No
`execute_method`	Ejecutar método del modelo	Depende

Configuración MCP para Claude Code

El archivo de configuración se encuentra en ~/.claude.json:

Ejecución local

claude mcp add odoo-mcp-server -- python odoo_mcp_server.py

{
  "mcpServers": {
    "odoo-mcp-server": {
      "command": "/bin/python",
      "args": [
        "odoo_mcp_server.py"
      ]
    }
  }
}

Docker (host.docker.internal)

Aplicable cuando Odoo se ejecuta localmente:

claude mcp add odoo-mcp-server -- docker run -i --rm --add-host=host.docker.internal:host-gateway -e ODOO_URL=http://host.docker.internal:8069 -e ODOO_DATABASE=odoo19 -e ODOO_API_KEY=your_api_key_here odoo-mcp-server

{
  "mcpServers": {
    "odoo-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--add-host=host.docker.internal:host-gateway",
        "-e",
        "ODOO_URL=http://host.docker.internal:8069",
        "-e",
        "ODOO_DATABASE=odoo19",
        "-e",
        "ODOO_API_KEY=your_api_key_here",
        "odoo-mcp-server"
      ]
    }
  }
}

Docker (red host)

Usando el modo de red del host:

claude mcp add odoo-mcp-server -- docker run -i --rm --network host -e ODOO_URL=http://localhost:8069 -e ODOO_DATABASE=odoo19 -e ODOO_API_KEY=your_api_key_here odoo-mcp-server

{
  "mcpServers": {
    "odoo-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network",
        "host",
        "-e",
        "ODOO_URL=http://localhost:8069",
        "-e",
        "ODOO_DATABASE=odoo19",
        "-e",
        "ODOO_API_KEY=your_api_key_here",
        "odoo-mcp-server"
      ]
    }
  }
}

Docker (Odoo remoto)

claude mcp add odoo-mcp-server -- docker run -i --rm -e ODOO_URL=https://example.com/ -e ODOO_DATABASE=odoo19 -e ODOO_API_KEY=your_api_key_here odoo-mcp-server

{
  "mcpServers": {
    "odoo-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ODOO_URL=https://example.com/",
        "-e",
        "ODOO_DATABASE=odoo19",
        "-e",
        "ODOO_API_KEY=your_api_key_here",
        "odoo-mcp-server"
      ]
    }
  }
}

Construcción de Docker

docker build -t odoo-mcp-server .

Configuración MCP para Gemini

gemini mcp add --scope user odoo-mcp docker -- run -i --rm --add-host=host.docker.internal:host-gateway -e ODOO_URL=http://host.docker.internal:8069 -e ODOO_DATABASE=odoo19 -e ODOO_API_KEY=your_api_key_here odoo-mcp-server

{
  "mcpServers": {
    "odoo-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--add-host=host.docker.internal:host-gateway",
        "-e",
        "ODOO_URL=http://host.docker.internal:8069",
        "-e",
        "ODOO_DATABASE=odoo19",
        "-e",
        "ODOO_API_KEY=your_api_key_here",
        "odoo-mcp-server"
      ]
    }
  }
}

Mecanismos de seguridad

Modo de solo lectura

Configura READONLY_MODE=true para habilitar el modo de solo lectura, adecuado para consultas en entornos de producción:

Las herramientas de escritura (create_record, update_record, delete_record, execute_method) se ocultan directamente mediante etiquetas FastMCP, por lo que el LLM no verá estas herramientas.

Doble confirmación de eliminación

delete_record tiene un mecanismo de confirmación integrado; el LLM debe llamar primero con confirm=False para obtener un aviso de confirmación, y solo después de que el usuario esté de acuerdo, puede ejecutar la eliminación con confirm=True.

Verificación de salud (Health check)

En el modo de transporte HTTP/SSE se proporciona el endpoint /health:

curl http://localhost:8000/health
# {"status": "healthy", "service": "odoo-mcp-server", "version": "1.0.0"}

Aplicable para healthcheck de Docker, sondas de Kubernetes, balanceadores de carga. No afecta en el modo stdio.

odoo19-mcp-server