mcp-odbc

Einführung

Dieses Dokument beschreibt die Einrichtung und Verwendung eines generischen ODBC-Servers für das Model Context Protocol (MCP), genannt mcp-odbc Server. Er wurde entwickelt, um Large Language Models transparenten Zugriff auf ODBC-zugängliche Datenquellen über einen für einen bestimmten ODBC-Connector (auch ODBC-Treiber genannt) konfigurierten Datenquellennamen zu ermöglichen.

Serverimplementierung

Dieser MCP-Server für ODBC ist eine kleine TypeScript-Schicht, die auf node-odbc aufbaut. Er leitet Aufrufe über node.js (insbesondere unter Verwendung von npx für TypeScript) an den lokalen ODBC-Treibermanager des Hostsystems weiter.

Einrichtung und Voraussetzungen der Betriebsumgebung

Die folgenden Beispiele beziehen sich zwar auf den Virtuoso ODBC Connector, diese Anleitung funktioniert jedoch auch mit anderen ODBC Connectors. Wir freuen uns über Ihre Codebeiträge und die Einsendung von Anwendungsdemos zu anderen Datenbankmanagementsystemen (DBMS), die wir in dieses Projekt integrieren können.

Wichtige Systemkomponenten

1. Überprüfen Sie die node.js -Version. Wenn sie nicht mindestens 21.1.0 oder höher ist, führen Sie ein Upgrade oder eine explizite Installation durch:
   nvm install v21.1.0
2. Installieren Sie MCP-Komponenten mit:
   npm install @modelcontextprotocol/sdk zod tsx odbc dotenv
3. Legen Sie die nvm Version mit folgendem Befehl fest:
   nvm alias default 21.1.0

Installation

1. Laufen
   git clone https://github.com/OpenLinkSoftware/mcp-odbc-server.git
2. Verzeichnis ändern
   cd mcp-odbc-server
3. Laufen
   npm init -y
4. Laufen
   npm install @modelcontextprotocol/sdk zod tsx odbc dotenv

Überprüfungen der unixODBC-Laufzeitumgebung

1. Überprüfen Sie die Installationskonfiguration (d. h. den Speicherort der wichtigsten INI-Dateien), indem Sie Folgendes ausführen:
   odbcinst -j
2. Listen Sie die verfügbaren Datenquellennamen (DSNs) auf, indem Sie Folgendes ausführen:
   odbcinst -q -s

Umgebungsvariablen

Aus Sicherheitsgründen sollten Sie die .env Datei im selben Verzeichnis wie mcp-ser verwenden, um Bindungen für den ODBC-Datenquellennamen ( ODBC_DSN ), den Benutzer ( ODBC_USER ), das Kennwort ( ODBC_PWD ), die ODBC-INI ( ODBCINI ) und, wenn Sie die OpenLink AI Layer (OPAL) über ODBC verwenden möchten, den Ziel-API-Schlüssel des Large Language Model (LLM) ( API_KEY ) festzulegen.

Verwendung

Werkzeuge

Nach erfolgreicher Installation stehen den MCP-Clientanwendungen die folgenden Tools zur Verfügung.

Überblick

Detaillierte Beschreibung

• get_schemas
  • Rufen Sie eine Liste aller Schemanamen aus der verbundenen Datenbank ab und geben Sie sie zurück.
  • Eingabeparameter:
    • user (Zeichenfolge, optional): Datenbankbenutzername. Der Standardwert ist "demo" .
    • password (Zeichenfolge, optional): Datenbankkennwort. Der Standardwert ist "demo" .
    • dsn (Zeichenfolge, optional): Name der ODBC-Datenquelle. Der Standardwert ist "Local Virtuoso" .
  • Gibt ein JSON-String-Array mit Schemanamen zurück.
• get_tables
  • Ruft eine Liste mit Informationen zu Tabellen in einem angegebenen Schema ab und gibt sie zurück. Wenn kein Schema angegeben ist, wird das Standardschema der Verbindung verwendet.
  • Eingabeparameter:
    • schema (Zeichenfolge, optional): Datenbankschema zum Filtern von Tabellen. Standardmäßig wird der Verbindungsstandard verwendet.
    • user (Zeichenfolge, optional): Datenbankbenutzername. Der Standardwert ist "demo" .
    • password (Zeichenfolge, optional): Datenbankkennwort. Der Standardwert ist "demo" .
    • dsn (Zeichenfolge, optional): Name der ODBC-Datenquelle. Der Standardwert ist "Local Virtuoso" .
  • Gibt eine JSON-Zeichenfolge mit Tabelleninformationen zurück (z. B. TABLE_CAT , TABLE_SCHEM , TABLE_NAME , TABLE_TYPE ).
• filter_table_names
  • Filtert und gibt Informationen zu Tabellen zurück, deren Namen eine bestimmte Teilzeichenfolge enthalten.
  • Eingabeparameter:
    • q (Zeichenfolge, erforderlich): Die Teilzeichenfolge, nach der in Tabellennamen gesucht werden soll.
    • schema (Zeichenfolge, optional): Datenbankschema zum Filtern von Tabellen. Standardmäßig wird der Verbindungsstandard verwendet.
    • user (Zeichenfolge, optional): Datenbankbenutzername. Der Standardwert ist "demo" .
    • password (Zeichenfolge, optional): Datenbankkennwort. Der Standardwert ist "demo" .
    • dsn (Zeichenfolge, optional): Name der ODBC-Datenquelle. Der Standardwert ist "Local Virtuoso" .
  • Gibt eine JSON-Zeichenfolge zurück, die Informationen zu übereinstimmenden Tabellen enthält.
• describe_table
  • Rufen Sie detaillierte Informationen zu den Spalten einer bestimmten Tabelle ab und geben Sie sie zurück.
  • Eingabeparameter:
    • schema (Zeichenfolge, erforderlich): Der Datenbankschemaname, der die Tabelle enthält.
    • table (Zeichenfolge, erforderlich): Der Name der zu beschreibenden Tabelle.
    • user (Zeichenfolge, optional): Datenbankbenutzername. Der Standardwert ist "demo" .
    • password (Zeichenfolge, optional): Datenbankkennwort. Der Standardwert ist "demo" .
    • dsn (Zeichenfolge, optional): Name der ODBC-Datenquelle. Der Standardwert ist "Local Virtuoso" .
  • Gibt eine JSON-Zeichenfolge zurück, die die Spalten der Tabelle beschreibt (z. B. COLUMN_NAME , TYPE_NAME , COLUMN_SIZE , IS_NULLABLE ).
• query_database
  • Führen Sie eine Standard-SQL-Abfrage aus und geben Sie die Ergebnisse im JSON-Format zurück.
  • Eingabeparameter:
    • query (Zeichenfolge, erforderlich): Die auszuführende SQL-Abfragezeichenfolge.
    • user (Zeichenfolge, optional): Datenbankbenutzername. Der Standardwert ist "demo" .
    • password (Zeichenfolge, optional): Datenbankkennwort. Der Standardwert ist "demo" .
    • dsn (Zeichenfolge, optional): Name der ODBC-Datenquelle. Der Standardwert ist "Local Virtuoso" .
  • Gibt Abfrageergebnisse als JSON-Zeichenfolge zurück.
• query_database_md
  • Führen Sie eine Standard-SQL-Abfrage aus und geben Sie die Ergebnisse als Markdown-Tabelle formatiert zurück.
  • Eingabeparameter:
    • query (Zeichenfolge, erforderlich): Die auszuführende SQL-Abfragezeichenfolge.
    • user (Zeichenfolge, optional): Datenbankbenutzername. Der Standardwert ist "demo" .
    • password (Zeichenfolge, optional): Datenbankkennwort. Der Standardwert ist "demo" .
    • dsn (Zeichenfolge, optional): Name der ODBC-Datenquelle. Der Standardwert ist "Local Virtuoso" .
  • Gibt Abfrageergebnisse als Markdown-Tabellenzeichenfolge zurück.
• query_database_jsonl
  • Führen Sie eine Standard-SQL-Abfrage aus und geben Sie die Ergebnisse im JSON-Zeilenformat (JSONL) zurück (ein JSON-Objekt pro Zeile).
  • Eingabeparameter:
    • query (Zeichenfolge, erforderlich): Die auszuführende SQL-Abfragezeichenfolge.
    • user (Zeichenfolge, optional): Datenbankbenutzername. Der Standardwert ist "demo" .
    • password (Zeichenfolge, optional): Datenbankkennwort. Der Standardwert ist "demo" .
    • dsn (Zeichenfolge, optional): Name der ODBC-Datenquelle. Der Standardwert ist "Local Virtuoso" .
  • Gibt Abfrageergebnisse als JSONL-Zeichenfolge zurück.
• spasql_query
  • Führen Sie eine SPASQL-Abfrage (SQL/SPARQL-Hybrid) aus, um Ergebnisse zurückzugeben. Dies ist eine Virtuoso-spezifische Funktion.
  • Eingabeparameter:
    • query (Zeichenfolge, erforderlich): Die SPASQL-Abfragezeichenfolge.
    • max_rows (Zahl, optional): Maximale Anzahl der zurückzugebenden Zeilen. Der Standardwert ist 20 .
    • timeout (Zahl, optional): Abfrage-Timeout in Millisekunden. Der Standardwert ist 30000 , also 30 Sekunden.
    • user (Zeichenfolge, optional): Datenbankbenutzername. Der Standardwert ist "demo" .
    • password (Zeichenfolge, optional): Datenbankkennwort. Der Standardwert ist "demo" .
    • dsn (Zeichenfolge, optional): Name der ODBC-Datenquelle. Der Standardwert ist "Local Virtuoso" .
  • Gibt das Ergebnis des zugrunde liegenden gespeicherten Prozeduraufrufs zurück (z. B. Demo.demo.execute_spasql_query ).
• sparql_query
  • Führen Sie eine SPARQL-Abfrage aus und geben Sie Ergebnisse zurück. Dies ist eine Virtuoso-spezifische Funktion.
  • Eingabeparameter:
    • query (Zeichenfolge, erforderlich): Die SPARQL-Abfragezeichenfolge.
    • format (Zeichenfolge, optional): Gewünschtes Ergebnisformat. Standardmäßig 'json' .
    • timeout (Zahl, optional): Abfrage-Timeout in Millisekunden. Der Standardwert ist 30000 , also 30 Sekunden.
    • user (Zeichenfolge, optional): Datenbankbenutzername. Der Standardwert ist "demo" .
    • password (Zeichenfolge, optional): Datenbankkennwort. Der Standardwert ist "demo" .
    • dsn (Zeichenfolge, optional): Name der ODBC-Datenquelle. Der Standardwert ist "Local Virtuoso" .
  • Gibt das Ergebnis des zugrunde liegenden Funktionsaufrufs zurück (z. B. "UB".dba."sparqlQuery" ).
• virtuoso_support_ai
  • Nutzt eine Virtuoso-spezifische KI-Assistentenfunktion und übergibt eine Eingabeaufforderung und einen optionalen API-Schlüssel. Dies ist eine Virtuoso-spezifische Funktion.
  • Eingabeparameter:
    • prompt (Zeichenfolge, erforderlich): Der Eingabeaufforderungstext für die KI-Funktion.
    • api_key (Zeichenfolge, optional): API-Schlüssel für den KI-Dienst. Standardmäßig "none" .
    • user (Zeichenfolge, optional): Datenbankbenutzername. Der Standardwert ist "demo" .
    • password (Zeichenfolge, optional): Datenbankkennwort. Der Standardwert ist "demo" .
    • dsn (Zeichenfolge, optional): Name der ODBC-Datenquelle. Der Standardwert ist "Local Virtuoso" .
  • Gibt das Ergebnis des Funktionsaufrufs des AI Support Assistant zurück (z. B. DEMO.DBA.OAI_VIRTUOSO_SUPPORT_AI ).

Grundlegende Installationstests und Fehlerbehebung

MCP-Inspektor-Tool

Canonical MCP Inspector Tool Edition

1. Starten Sie den Inspector aus dem MCP-Server-Verzeichnis/-Ordner mit dem folgenden Befehl:
   ODBCINI=/Library/ODBC/odbc.ini npx -y @modelcontextprotocol/inspector npx tsx ./src/main.ts
2. Klicken Sie auf die Schaltfläche „Verbinden“ und dann auf die Registerkarte „Tools“, um zu beginnen.

OpenLink MCP Inspector Tool Edition

Dies ist ein Fork der kanonischen Edition, der einen Bugfix für die JSON-Verarbeitung im Zusammenhang mit der Verwendung mit diesem MCP-Server enthält.

1. laufen
   git clone git@github.com:OpenLinkSoftware/inspector.git cd inspector
2. laufen
   npm run start
3. Geben Sie den folgenden Wert in das Eingabefeld Arguments der MCP Inspectors-Benutzeroberfläche von http://localhost:6274 ein.
   tsx /path/to/mcp-odbc-server/src/main.ts
4. Klicken Sie auf die Schaltfläche Connect , um Ihre Sitzung mit dem angegebenen MCP-Server zu initialisieren

Kompatibilität von Apple Silicon (ARM64) mit MCP ODBC-Serverproblemen

Konfliktproblem zwischen Node x86_64 und arm64

Möglicherweise ist die x86_64- und nicht die arm64-Edition von node vorhanden, aber die ODBC-Brücke und der MCP-Server sind arm64-basierte Komponenten.

Sie können dieses Problem lösen, indem Sie die folgenden Schritte ausführen:

1. Deinstallieren Sie die x86_64-Edition von node , indem Sie Folgendes ausführen:
   nvm uninstall 21.1.0
2. Führen Sie den folgenden Befehl aus, um zu bestätigen, dass sich Ihre aktuelle Shell im arm64-Modus befindet:
   arch
   • Wenn x86_64 zurückgegeben wird, führen Sie den folgenden Befehl aus, um den aktiven Modus zu ändern:
     arch arm64
3. Installieren Sie die arm64-Edition von node , indem Sie Folgendes ausführen:
   nvm install 21.1.0

Inkompatibilität zwischen Knoten und ODBC-Bridge-Schicht

Beim Versuch, einen Model Context Protocol (MCP) ODBC-Server auf Apple Silicon-Rechnern zu verwenden, können Architekturfehler auftreten. Diese treten auf, weil das native ODBC-Modul von Node.js ( odbc.node ) für die ARM64-Architektur kompiliert ist, aber die x86_64-basierte Version der unixODBC-Laufzeit geladen wird.

Typische Fehlermeldung:

Sie lösen dieses Problem, indem Sie die folgenden Schritte ausführen:

1. Überprüfen Sie, ob Ihr Node.js im ARM64-Modus ausgeführt wird:
   node -p "process.arch" # Should output: `arm64`
2. Installieren Sie unixODBC für ARM64:
   # Verify Homebrew is running in ARM64 mode which brew # Should point to /opt/homebrew/bin/brew # Remove existing unixODBC brew uninstall --force unixodbc # Install ARM64 version arch -arm64 brew install unixodbc
3. Erstellen Sie das Node.js ODBC-Modul für ARM64 neu:
   # Navigate to your project cd /path/to/mcp-odbc-server # Remove existing module rm -rf node_modules/odbc # Set architecture environment variable export npm_config_arch=arm64 # Reinstall with force build npm install odbc --build-from-source
4. Überprüfen Sie, ob das Modul jetzt ARM64 ist:
   file node_modules/odbc/lib/bindings/napi-v8/odbc.node # Should show "arm64" instead of "x86_64"

Wichtige Punkte

• Sowohl unixODBC als auch das Node.js ODBC-Modul müssen ARM64-kompatibel sein
• Die Verwendung von Umgebungsvariablen ( export npm_config_arch=arm64 ) ist zuverlässiger als npm-Konfigurationsbefehle
• Überprüfen Sie die Architektur immer mit dem file oder node -p "process.arch"
• Bei der Verwendung von Homebrew auf Apple Silicon können Befehle mit arch -arm64 versehen werden, um die Verwendung von ARM64-Binärdateien zu erzwingen.

MCP-Anwendungsnutzung

Claude Desktop-Konfiguration

Der Pfad für diese Konfigurationsdatei lautet: ~{username}/Library/Application Support/Claude/claude_desktop_config.json .

Claude Desktop-Nutzung

1. Starten Sie die Anwendung.
2. Wenden Sie die Konfiguration (von oben) über Einstellungen | Entwickler-Benutzeroberfläche an.
3. Stellen Sie sicher, dass Sie über eine funktionierende ODBC-Verbindung zu einem Datenquellennamen (DSN) verfügen.
4. Präsentieren Sie eine Eingabeaufforderung zur Abfrageausführung, z. B.
   Execute the following query: SELECT TOP * from Demo..Customers

Cline (Visual Studio-Erweiterung)-Konfiguration

Der Pfad für diese Konfigurationsdatei lautet: ~{username}/Library/Application\ Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Cline (Visual Studio-Erweiterung)-Verwendung

1. Verwenden Sie Umschalt+Befehl+P, um die Befehlspalette zu öffnen.
2. Geben Sie ein: Cline .
3. Wählen Sie: Cline-Ansicht, wodurch die Cline-Benutzeroberfläche in der VSCode-Seitenleiste geöffnet wird.
4. Verwenden Sie das Symbol mit den vier Quadraten, um auf die Benutzeroberfläche zum Installieren und Konfigurieren von MCP-Servern zuzugreifen.
5. Wenden Sie die Cline-Konfiguration (von oben) an.
6. Kehren Sie zur Hauptbenutzeroberfläche der Erweiterung zurück und starten Sie eine neue Aufgabe, die die Verarbeitung der folgenden Eingabeaufforderung anfordert:
   "Execute the following query: SELECT TOP 5 * from Demo..Customers"

Cursorkonfiguration

Über das Einstellungszahnrad öffnen Sie das Konfigurationsmenü, das den MCP-Menüpunkt zum Registrieren und Konfigurieren mcp servers enthält.

Cursorverwendung

1. Verwenden Sie die Tastenkombination Command + I oder Control + I um die Chat-Oberfläche zu öffnen.
2. Wählen Sie Agent aus der Dropdown-Liste unten links in der Benutzeroberfläche aus. Die Standardeinstellung ist Ask .
3. Geben Sie Ihre Eingabeaufforderung ein und qualifizieren Sie die Verwendung des mcp-server for odbc mit dem Muster: @odbc {rest-of-prompt} .
4. Klicken Sie auf „Akzeptieren“, um die Abfrage auszuführen.

Verwandt

• Screencast zur Verwendung von MCP Inspector
• Screencast zur grundlegenden Verwendung des Claude-Desktops
• Screencast zur grundlegenden Verwendung der Cline Visual Studio Code-Erweiterung
• Screencast zur grundlegenden Verwendung des Cursor-Editors