Odoo Assistant MCP Server

Ein virtueller Odoo-Mitarbeiter über das Model Context Protocol (MCP). Dieser Server gibt Odoos Geschäftslogik, Datensätze und Workflows für LLMs frei, sodass diese sicher Odoo-Daten abfragen, erstellen, aktualisieren und bearbeiten können.

Schnellstart

1. Installieren

Führen Sie den Server direkt aus:

uvx odoo-assistant

Oder installieren Sie ihn in Ihrer Umgebung:

uv pip install odoo-assistant

Die Installation aus dem Quellcode für die Entwicklung bleibt möglich:

uv pip install git+https://github.com/singleflo/odoo-assistant-mcp

2. Umgebungsvariablen konfigurieren

Zwei Variablen sind erforderlich; alles andere wird automatisch ermittelt oder hat einen Standardwert:

• ODOO_BASE_URL: Die Basis-URL Ihrer Odoo-Instanz (z. B. https://mycompany.odoo.com).

• ODOO_API_KEY: Der Odoo-API-Schlüssel (Odoo 14+, erstellen unter Einstellungen > Benutzer > API-Schlüssel > Neu). Ein Kontopasswort wird nicht akzeptiert: Ein Schlüssel ist pro Benutzer, begrenzt und eigenständig widerrufbar.

Optionale Konfiguration:

• ODOO_DB: Der Datenbankname. Wird automatisch ermittelt, wenn die Instanz genau eine Datenbank bedient; erforderlich, wenn mehrere vorhanden sind – der Fehler listet alle auf.

• ODOO_USER: Der Login. Wird aus dem Schlüssel ermittelt, was bis zu 59 zusätzliche Roundtrips kosten kann; die Erkennung schlägt fehl, wenn die uid des Schlüsselbesitzers 60 oder höher ist. Das Setzen vermeidet diese Abfrage.

• ODOO_MCP_MAX_LEVEL: Die höchste Sicherheitsstufe, die dieser Server ausführen darf, 0 bis 4 (Standard: 3). Damit machen Sie den Server schreibgeschützt oder erlauben das Löschen – siehe Die Obergrenze wählen.

• ODOO_MCP_PROTECTED_HOSTS: Kommagetrennte Hosts, für die dieser Server Schreibvorgänge ablehnt (standardmäßig leer – kein Host ist im Paket fest integriert). Ein gelisteter Host erlaubt weiterhin Lesezugriffe; zum Schreiben muss ODOO_ALLOW_PROD_WRITE=yes als bewusste Überschreibung gesetzt werden.

Related MCP server: mcp-server-odoo

Sicherheitsebene

Jeder Schreibvorgang und jede Aktion durchläuft vor der Ausführung an Odoo einen dynamischen Sicherheitsklassifizierer. Operationen werden in die Stufen L0 bis L5 eingeteilt:

Die Obergrenze wählen

ODOO_MCP_MAX_LEVEL legt die höchste Stufe fest, die dieser Server ausführen darf. Jeder Wert ist kumulativ – er erlaubt seine eigene Stufe und alles darunter:

Zwei Verhaltensweisen sollten Sie kennen, bevor Sie eine Zahl wählen:

• 5 schaltet L5 nicht frei. Beide L5-Varianten werden abgelehnt, bevor die Obergrenze überhaupt gelesen wird. L5_PRIVATE wird abgelehnt, weil Odoo selbst jede Methode ablehnt, die mit _ beginnt, sodass keine Obergrenze sie bereitstellen könnte; L5_UNKNOWN wird abgelehnt, weil eine Methode, die niemand klassifiziert hat, definitionsgemäß ungeprüfte Auswirkungen hat. Der Weg, eine solche Methode zu erlauben, besteht darin, sie in WRITE_L1/L3/L4 in safety_layer.py hinzuzufügen – im Code, überprüft – niemals durch Konfiguration.

• Ein ungültiger Wert verhindert den Start. ODOO_MCP_MAX_LEVEL="O" führt zu einem Fehler, anstatt auf den Standardwert zurückzufallen, weil der Standardwert schreibfähig ist: Ein Tippfehler darf Ihnen keinen schreibenden Server bescheren, den Sie für schreibgeschützt hielten.

Die Obergrenze wird out-of-band von einem Menschen gesetzt und beim Start aus der Prozessumgebung gelesen. Das gegen diesen Server laufende Modell kann sie nicht erhöhen; wenn ein Aufruf die Obergrenze überschreitet, nennt die Ablehnung die erforderliche Stufe, sodass der Agent erklären kann, was die Operation ändern würde, und die Entscheidung Ihnen überlässt.

Beachten Sie, dass dies die Autorität dieses Servers ist, nicht die des Kontos. Ein Agent mit Shell-Zugriff kann einen MCP-Server jederzeit umgehen, indem er Odoo direkt aufruft. Eine Einschränkung, die unabhängig vom Client gelten muss, gehört in die Odoo-Zugriffsrechte des Benutzers, dem der API-Schlüssel gehört, wo der Odoo-Server sie durchsetzt.

Odoo-Versionsunterstützung

Odoo 14.0 ist die absolute Mindestversion, die unterstützt wird, da dieser Server nur mit API-Schlüsseln authentifiziert, die es in Odoo 13 oder älter nicht gibt.

Pfad zur API-Schlüsselgenerierung

Um einen API-Schlüssel zu generieren, melden Sie sich bei Ihrer Odoo-Instanz an und navigieren Sie zu: Einstellungen / Mein Profil → Kontosicherheit → Neuer API-Schlüssel

Transport- und Deprecation-Hinweis

Der Client erkennt automatisch, ob die native JSON-2-API unter /json/2/<model>/<method> verfügbar ist (die Authorization: bearer <API_KEY> verwendet) und fällt auf XML-RPC zurück, wenn nicht. Bitte beachten Sie, dass XML-RPC und JSON-RPC in Odoo 19 veraltet sind und für Odoo 22 zur Entfernung vorgesehen sind.

Quellen

• Odoo 14.0 Externe API-Dokumentation (Einführung der API-Schlüssel)

• Odoo 19.0 Externe API-Dokumentation (JSON-2)

• Odoo 19.0 Externe RPC-API-Dokumentation (XML-RPC-Deprecation)

• Odoo Standard- und erweiterte Support-Richtlinie (Support-Zeitpläne)

Tools und Ressourcen

Der Server stellt 19 Tools und 2 Ressourcentypen bereit:

Tools

1. search_read: Datensätze in einem Aufruf suchen und lesen (Odoo search_read).

2. read_record: Einen Datensatz nach ID lesen, immer mit benannten Feldern.

3. count_records: Die Anzahl der Datensätze zählen, die einer Domain entsprechen (Odoo search_count).

4. instance_overview: Die verbundene Instanz zusammenfassen: Version, Unternehmen, Volumen pro Bereich, hauseigene Module, Anomalien.

5. required_fields: Auflisten, was Odoo vor einem create auf einem Modell verlangt, den Standardwert, den es anwenden würde, und wie vorhandene Datensätze es tatsächlich nutzen.

6. create_record: Einen Datensatz erstellen, wobei ein vorhandener Treffer wiederverwendet wird, wenn unique_on angegeben ist.

7. write_record: Feldwerte in einen Datensatz schreiben und melden, was sich tatsächlich geändert hat.

8. run_action: Eine Workflow-Methode ausführen und den zurückgelassenen Status melden.

9. cancel_record: Einen Datensatz über action_cancel stornieren, dem zurückgegebenen Assistenten folgend.

10. notify_user: Benutzer im Chatter eines Datensatzes benachrichtigen. Standardmäßig intern.

11. create_activity: Eine Aktivität planen: die einzige Benachrichtigung, die eine Frist trägt.

12. download_docs: Alle Dokumente eines Datensatzes auf die Festplatte speichern, einschließlich Chatter-Dateien.

13. generate_pdf: Das PDF eines Datensatzes rendern und zurückgeben, wo es gespeichert wurde.

14. list_message_targets: Auflisten, wer benachrichtigt werden kann und wo – interne Benutzer mit Anwesenheit (online/abwesend/offline) und die offenen Konversationen des Aufrufers. Vor dem Senden abfragen.

15. read_conversation: Eine Discuss-Konversation lesen, neueste zuerst.

16. send_direct_message: Eine 1-zu-1-Discuss-Nachricht senden, die in Echtzeit in der Chat-Systray des Benutzers erscheint – keine E-Mail, erreicht ihn unabhängig von seiner Benachrichtigungseinstellung.

17. send_channel_message: In einem vorhandenen Discuss-Kanal posten, wobei ein Raum abgelehnt wird, der einen Nicht-Mitarbeiter enthält.

18. explore_module: Die Struktur eines Moduls durch Abfragen der Live-Instanz erkunden.

19. list_known_modules: Die Module auflisten, die dieser Server gelernt hat: Name, Erstellungsdatum, Datensätze.

Die Tools 10-11 (notify_user, create_activity) benachrichtigen ÜBER einen Datensatz und landen in der Inbox-Glocke; die Tools 14-17 sind Discuss-Konversationen, die in der Chat-Systray landen. "Nachricht an Benutzer X" ist die zweite Art – send_direct_message, nicht notify_user.

Ressourcen

• odoo://skill: Zugriff auf die Odoo-Assistant-Fähigkeitsanweisungen.

• odoo://ref/*: Zugriff auf generierte Referenzdokumentation für erkundete Module.

Host-Konfigurationsbeispiele

Jedes Beisiel unten enhält nur das Wesentliche: die beien erfordelichen Variablen und die Oberrenze – die eine Einstellung, die entsheiedet, ob dieser Server schreiben darf, sichtbar in der Datei, die der Mensch besitzt. Die Datenbank und der Login werden ermittelt, und 3 ist der Standard der Oberrenze. Beachten Sie die Anführungszeichen: Umgebungswerte sind Zeichenketten.

Claude Desktop

Fügen Sie dies zu Ihrer claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

Cursor

Fügen Sie dies zu Ihrer .cursor/mcp.json hinzu oder konfigurieren Sie es in der Cursor-Einstellungs-UI:

{
  "mcpServers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

VS Code Copilot

Fügen Sie dies zu Ihrer VS-Code-settings.json hinzu:

{
  "mcp.servers": {
    "odoo-assistant": {
      "command": "uvx",
      "args": [
        "odoo-assistant"
      ],
      "env": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

opencode

Fügen Sie dies zu opencode.json oder .opencode/opencode.json in Ihrem Projekt hinzu oder zu ~/.config/opencode/opencode.json, um den Server überall verfügbar zu machen:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "odoo-assistant": {
      "type": "local",
      "enabled": true,
      "command": [
        "uvx",
        "odoo-assistant"
      ],
      "timeout": 120000,
      "environment": {
        "ODOO_BASE_URL": "https://mycompany.odoo.com",
        "ODOO_API_KEY": "your-api-key-here",
        "ODOO_MCP_MAX_LEVEL": "3"
      }
    }
  }
}

Die Struktur von opencode unterscheidet sich von den oben genannten Hosts auf eine Weise, die diese direkt ablehnen: Der Schlüssel ist mcp (nicht mcpServers), type ist erforderlich, command ist ein einzelnes Array, das das Programm und seine Argumente enthält (es gibt kein separates args), und der Umgebungsblock ist environment (nicht env).

Setzen Sie timeout bewusst. Der Standardwert beträgt 5000 ms, und der erste Aufruf einer Sitzung umfasst die Authentifizierung sowie für instance_overview Dutzende von XML-RPC-Roundtrips – bequem über fünf Sekunden gegen eine echte Instanz.

opencode liest seine Konfiguration einmal beim Start und lädt sie nicht neu, also beenden und neu starten nach der Bearbeitung. Alles, was Sie hier ändern – einschließlich der Obergrenze – wirt erst beim nächsten Staret wirksam.

ChatGPT (Benutzerdefinierte Konnektoren)

Um diesen Server über benutzerdefinierte Konnektoren mit ChatGPT zu verbinden:

1. Gehen Sie zu Einstellungen → Konnektoren → Konnektor hinzufügen.

2. Geben Sie die Server-URL ein oder wählen Sie aus dem Registry.

3. Geben Sie bei Aufforderung Ihre Odoo-Anmeldedaten ein.

Hermes

Fügen Sie den Server über die Hermes CLI hinzu:

hermes mcp add odoo-assistant \
  --env ODOO_BASE_URL=https://mycompany.odoo.com \
  --env ODOO_API_KEY=your-api-key-here \
  --env ODOO_MCP_MAX_LEVEL=3 \
  --args run odoo-assistant

Die Beispiele lassen die optionalen Variablen aus. Setzen Sie ODOO_DB, wenn die Instanz mehrere Datenbanken bedient, ODOO_USER, um die uid-Abfrage zu überspringen, und ODOO_MCP_MAX_LEVEL, um die Obergrenze gegenüber dem Standardwert von 3 zu ändern.

License

Dieses Projekt ist unter der MIT-Lizenz lizenziert. Weitere Informationen finden Sie in der Datei LICENSE.