MCP-Oracle

Español | Deutsch

Ein MCP (Model Context Protocol) Server, der einen KI-Agenten mit einer Oracle-Datenbank verbindet.

Er stellt Werkzeuge bereit, um das Schema zu erkunden, PL/SQL-Quelltext zu lesen und SQL auszuführen. Er startet im Schreibgeschützt-Modus; Schreibvorgänge und Aufrufe von Stored Procedures werden durch ORACLE_ALLOW_WRITE=true aktiviert mulberry.

Er verwendet das offizielle Python-SDK (mcp) und python-oracledb,.

Falls ein Instant Client (oder das lib/-Verzeichnis eines ORACLE_HOME) gefunden wird, aktiviert er den Thick-Modus, andernfalls den Thin-Modus. Der Thick-Modus ist für ältere Instanzen (10g/11g) erforderlich, deren Passwortverifizierer im Thin-Modus nicht unterstützt wird.

Dieses Projekt ist nicht die offizielle Oracle-MCP-Suite (oracle/mcp). Dieses Repository richtet sich an Oracle-Cloud- und andere Oracle-Produkte. Dieser Server spricht direkt mit dem Listener Ihrer Datenbank.

Tools

run_query und execute_dml akzeptieren Bindevariablen (:name), sodass Sie Werte nicht in SQL einfügen müssen.

Related MCP server: Oracle DB MCP Server

Voraussetzungen

• Python 3.9+

• Zugriff auf eine Oracle-Instanz (Benutzer, Passwort, Host, Port und service_name)

• Für Oracle 10g/11g (oder wenn der Thin-Modus fehlschlägt): Oracle Instant Client oder das lib/-Verzeichnis eines ORACLE_HOME

Lokale Verwendung vs. Produktion

Diese README beschreibt die lokale Verwendung: Cursor oder Claude Desktop starten server.py auf Ihrem Computer über stdio (es wird kein HTTP-Port geöffnet).

Wenn der MCP-Server dauerhaft auf einem Server betrieben werden und Clients über das Netzwerk verbinden sollen:

• Linux (RedHat)

• Windows Server

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Kopieren Sie die Vorlage für die Umgebungsvariablen und füllen Sie Ihre Werte aus:

cp .env.example .env

Der Server lädt .env nicht automatisch. Diese Variablen müssen in der MCP-Client-Konfiguration (Cursor, Claude Desktop, u. Ä.) übergeben werden. Die .env-Datei dient als lokale Referenz; committen Sie sie nicht.

Umgebungsvariablen

Thick- vs. Thin-Modus

Beim Start prüft der Server ORACLE_CLIENT_LIB_DIR (bzw. ~/oracle/instantclient). Wenn dieser Ordner existiert, ruft er oracledb.init_oracle_client() auf und verwendet den Thick-Modus.

Beispiele:

# Instant Client (zip / RPM)
ORACLE_CLIENT_LIB_DIR=/Users/your_user/oracle/instantclient

# ORACLE_HOME 19c
ORACLE_CLIENT_LIB_DIR=/apps/oracle/product/19c/lib

Wenn kein nativer Client vorhanden ist, läuft der Server im Thin-Modus (in den meisten Fällen Oracle 12.1+).

Verwenden mit Cursor

Fügen Sie in Cursor einen Server zur MCP-Konfiguration hinzu (z. B. ~/.cursor/mcp.json oder die Projektkonfiguration):

{
  "mcpServers": {
    "oracle-mcp": {
      "command": "/Users/your_user/Development/oracle-mcp/.venv/bin/python",
      "args": ["/Users/your_user/Development/oracle-mcp/server.py"],
      "env": {
        "ORACLE_USER": "my_user",
        "ORACLE_PASSWORD": "my_password",
        "ORACLE_HOST": "127.0.0.1",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "ORCLPDB1",
        "ORACLE_ALLOW_WRITE": "false",
        "ORACLE_MAX_ROWS": "200"
      }
    }
  }
}

Verwenden Sie den absoluten Pfad zur .venv-Python, damit er in Client die Pakete mcp und oracledb findet.

Starten Sie Cursor neu (oder laden Sie die MCP-Server neu) und vergewissern Sie sich, dass oracle-mcp in der Werkzeugliste erscheint.

Verwenden mit Claude Desktop

In der claude_desktop_config.json:

{
  "mcpServers": {
    "oracle-mcp": {
      "command": "/Users/your_user/Development/oracle-mcp/.venv/bin/python",
      "args": ["/Users/your_user/Development/oracle-mcp/server.py"],
      "env": {
        "ORACLE_USER": "my_user",
        "ORACLE_PASSWORD": "my_password",
        "ORACLE_HOST": "127.0.0.1",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "ORCLPDB1",
        "ORACLE_ALLOW_WRITE": "false",
        "ORACLE_MAX_ROWS": "200"
      }
    }
  }
}

Manueller Start

Lokal spricht der Server MCP über stdio (er öffnet keinen HTTP-Port). Auf einem Produktionsserver ist ein Transport HTTP; siehe "Lokale Verwendung vs. Produktion" als Link.

source .venv/bin/activate
export ORACLE_USER=my_user
export ORACLE_PASSWORD=my_password
export ORACLE_HOST=127.0.0.1
export ORACLE_PORT=1521
export ORACLE_SERVICE_NAME=ORCLPDB1
python server.py

Ohne einen MCP-Client, der an stdin/stdout angeschlossen ist, sehen Sie keine interaktive Eingabeaufforderung; das ist normal.

Sicherheit

• Standardumgebung: ORACLE_ALLOW_WRITE=false: execute_dml und call_procedure schlagen mit PermissionError fehl.

• Wenn ORACLE_ALLOW_WRITE nicht true ist, gibt execute_dml und call_procedure Fehler.

• run_query lehnt Anweisungen ab, die mit INSERT, UPDATE, DELETE, MERGE, DROP, ALTER, TRUNCATE, CREATE, GRANT oder REVOKE beginnen.

• execute_dml akzeptiert nur INSERT, UPDATE, DELETE oder MERGE.

• Bevorzugen Sie Bind-Variablen (:name) und nicht das Einfügen von Werten in SQL.

• Verwenden Sie ein Benutzer mit minimalen Rechten, wenn Sie nur das Schema erkunden möchten.

• Committen Sie nicht Ihre .env-Datei oder Zugangsdaten in ein versioniertes mcp.json.

Abhängigkeiten

• mcp 1.2.0+

• oracledb 2.4.0+