Odoo 19 MCP Server (JSON-2 API)

odoo19-mcp-server MCP server

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

Youtube Tutorial - MCP Server selbst bauen! Odoo 19 + FastMCP vollständiges Entwicklungs-Tutorial

Odoo 19 MCP Server, Verbindung über JSON-2 API.

Dieses Projekt basiert auf dem Odoo 19 JSON-2 API vollständigen Leitfaden.

Ausführungsbildschirm

Tech-Stack

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

Architektur

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

MCP Kernkonzepte

Ressourcen vs. Tools

Eigenschaft	Ressourcen	Tools
Zweck	Bereitstellung von Kontextinformationen	Ausführung von Operationen/Aktionen
Auslösung	Client-gesteuert (z. B. Claude Code)	LLM entscheidet automatisch über den Aufruf
Parameter	Keine (oder URI-Parameter)	Vorhanden (müssen vom LLM generiert werden)
Analogie	Mitarbeiterhandbuch (Hintergrundwissen)	Werkzeugkasten (bei Bedarf verwenden)
HTTP-Analogie	GET (Lesen)	POST/PUT/DELETE (Operation)

Ressourcen - Dynamischer Kontext, Hintergrundinformationen, die das LLM von Anfang an kennt:

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

Tools - Operationen, die nur bei Bedarf aufgerufen werden:

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

Warum nicht Default Prompt verwenden?

Methode	Default Prompt	Ressource
Datenquelle	Fest im Code hinterlegt	Echtzeit-Abfrage von Odoo
Aktualisierungszeitpunkt	Bei der Bereitstellung	Bei jeder Verbindung
Benutzerwechsel	Informationen falsch	Automatisch korrekt

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

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

Fazit: Ressourcen sind „dynamischer Kontext“, kein statischer Text.

Referenz: MCP Resources | MCP Tools

Umgebungsvariablen

Variable	Beschreibung	Standardwert
`ODOO_URL`	Odoo Server URL	`http://localhost:8069`
`ODOO_DATABASE`	Datenbankname	-
`ODOO_API_KEY`	API-Key-Authentifizierung	-
`READONLY_MODE`	Schreibgeschützter Modus (Schreibvorgänge deaktiviert)	`false`

Erstellen Sie eine .env-Datei:

cp .env.example .env

Installation

pip install -r requirements.txt

Startmethode

Entwicklungsmodus (MCP Inspector)

fastmcp dev inspector odoo_mcp_server.py

Transportmodus (Transport)

Dieses Projekt unterstützt drei MCP-Transportmodi:

Modus	Beschreibung	Anwendungsszenario
`stdio`	Standard-Ein-/Ausgabe (Standard)	Claude Desktop, Cursor IDE, lokale Entwicklung
`http`	HTTP-Protokoll	Remote-Dienste, n8n, Web-App-Integration
`sse`	Server-Sent Events (veraltet)	Abwärtskompatibilität für ältere Clients

stdio vs. HTTP/SSE: Wo liegt die Rechenleistung?

Der entscheidende Unterschied zwischen den beiden Modi liegt darin, „wer den MCP-Server startet“ und „wo die Rechenleistung ausgeführt wird“:

stdio-Modus (lokale Rechenleistung)

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

Der Client (z. B. Claude Desktop) startet den MCP-Server als untergeordneten Prozess
Der MCP-Server nutzt die CPU/RAM Ihres Computers
Der Server startet/beendet sich zusammen mit dem Client

HTTP/SSE-Modus (Remote-Rechenleistung)

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

Der MCP-Server läuft unabhängig auf einem Cloud-/Remote-Host
Mehrere Clients können gleichzeitig mit demselben Server verbunden sein
Geeignet für Team-Sharing, n8n-Integration, Produktionsumgebungen

Starten der verschiedenen Modi

# 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

Cloud-Bereitstellung (HTTP-Modus)

Docker Compose Beispiel:

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

Client-Konfiguration (Claude) auf URL-Verbindung umstellen:

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"
    }
  }
}

MCP Ressourcen

URI	Beschreibung
`odoo://models`	Alle Modelle auflisten
`odoo://model/{model_name}`	Felddefinitionen des Modells abrufen
`odoo://record/{model_name}/{record_id}`	Einzelnen Datensatz abrufen
`odoo://user`	Informationen zum aktuell angemeldeten Benutzer
`odoo://company`	Informationen zum Unternehmen des aktuellen Benutzers

MCP Tools

Tool	Beschreibung	Schreibgeschützt
`list_models`	Verfügbare Modelle auflisten/suchen	Ja
`get_fields`	Felddefinitionen des Modells abrufen	Ja
`search_records`	Datensätze suchen	Ja
`count_records`	Datensätze zählen	Ja
`read_records`	Datensatz mit angegebener ID lesen	Ja
`create_record`	Datensatz erstellen	Nein
`update_record`	Datensatz aktualisieren	Nein
`delete_record`	Datensatz löschen (erfordert Bestätigung)	Nein
`execute_method`	Modellmethode ausführen	Abhängig

Claude Code MCP Konfiguration

Die Konfigurationsdatei befindet sich unter ~/.claude.json:

Lokale Ausführung

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)

Geeignet, wenn Odoo lokal ausgeführt wird:

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 (Host-Netzwerk)

Verwendung des Host-Netzwerkmodus:

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 (Remote Odoo)

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"
      ]
    }
  }
}

Docker Build

docker build -t odoo-mcp-server .

Gemini MCP Konfiguration

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"
      ]
    }
  }
}

Sicherheitsmechanismen

Schreibgeschützter Modus

Setzen Sie READONLY_MODE=true, um den schreibgeschützten Modus zu aktivieren, geeignet für Abfragen in Produktionsumgebungen:

Schreib-Tools (create_record, update_record, delete_record, execute_method) werden über FastMCP-Tags direkt ausgeblendet, das LLM sieht diese Tools nicht

Bestätigung beim Löschen

delete_record verfügt über einen integrierten Bestätigungsmechanismus. Das LLM muss zuerst mit confirm=False aufgerufen werden, um eine Bestätigungsaufforderung zu erhalten. Erst nach Zustimmung des Benutzers kann der Löschvorgang mit confirm=True ausgeführt werden.

Gesundheitsprüfung (Health Check)

Im HTTP/SSE-Transportmodus wird ein /health-Endpunkt bereitgestellt:

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

Geeignet für Docker-Healthchecks, Kubernetes-Probes und Load-Balancer-Prüfungen. Im stdio-Modus hat dies keine Auswirkungen.

Lizenz

Apache 2.0

odoo19-mcp-server