mcp-odbc

導入

このドキュメントでは、モデルコンテキストプロトコル（MCP）用の汎用ODBCサーバー（ mcp-odbcサーバー）のセットアップと使用方法について説明します。このサーバーは、特定のODBCコネクタ（ODBCドライバーとも呼ばれます）用に設定されたデータソース名を介して、大規模言語モデルからODBCアクセス可能なデータソースへの透過的なアクセスを提供するために開発されました。

サーバーの実装

このMCP Server for ODBCは、 node-odbc上に構築された小さなTypeScriptレイヤーです。node.js（TypeScriptの場合はnpxを使用）を介してnode.jsホストシステムのローカルODBCドライバーマネージ���ーへの呼び出しをルーティングします。

動作環境のセットアップと前提条件

以下の例はVirtuoso ODBCコネクタを対象としていますが、このガイドは他のODBCコネクタでも使用できます。他のデータベース管理システム（DBMS）に関するコードの投稿や使用方法のデモの提出を強く推奨します。これらの投稿は、本プロジェクトへの組み込みに活用させていただきます。

主要なシステムコンポーネント

1. node.jsバージョンを確認してください21.1.0以上でない場合は、次のコマンドで明示的にアップグレードまたはインストールしてください。
   nvm install v21.1.0
2. 次を使用して MCP コンポーネントをインストールします。
   npm install @modelcontextprotocol/sdk zod tsx odbc dotenv
3. 次を使用してnvmバージョンを設定します。
   nvm alias default 21.1.0

インストール

1. 走る
   git clone https://github.com/OpenLinkSoftware/mcp-odbc-server.git
2. ディレクトリを変更する
   cd mcp-odbc-server
3. 走る
   npm init -y
4. 走る
   npm install @modelcontextprotocol/sdk zod tsx odbc dotenv

unixODBC ランタイム環境チェック

1. 次のコマンドを実行して、インストール構成 (つまり、主要な INI ファイルの場所) を確認します。
   odbcinst -j
2. 次のコマンドを実行して、使用可能なデータ ソース名 (DSN) を一覧表示します。
   odbcinst -q -s

環境変数

適切なセキュリティ対策として、 mcp-serと同じディレクトリにある.envファイルを使用して、ODBC データ ソース名 ( ODBC_DSN )、ユーザー ( ODBC_USER )、パスワード ( ODBC_PWD )、ODBC INI ( ODBCINI )、および ODBC 経由で OpenLink AI Layer (OPAL) を使用する場合は対象の Large Language Model (LLM) API キー ( API_KEY ) のバインディングを設定する必要があります。

使用法

ツール

インストールが成功すると、次のツールが MCP クライアント アプリケーションで使用できるようになります。

概要

詳細な説明

• get_schemas
  • 接続されたデータベースからすべてのスキーマ名のリストを取得して返します。
  • 入力パラメータ:
    • user (文字列、オプション): データベースのユーザー名。デフォルトは"demo"です。
    • password (文字列、オプション): データベースのパスワード。デフォルトは"demo"です。
    • dsn (文字列、オプション): ODBC データソース名。デフォルトは"Local Virtuoso"です。
  • スキーマ名の JSON 文字列配列を返します。
• get_tables
  • 指定されたスキーマ内のテーブルに関する情報を含むリストを取得して返します。スキーマが指定されていない場合は、接続のデフォルトスキーマが使用されます。
  • 入力パラメータ:
    • schema (文字列, オプション): テーブルをフィルタリングするためのデータベーススキーマ。デフォルトは接続のデフォルトです。
    • user (文字列、オプション): データベースのユーザー名。デフォルトは"demo"です。
    • password (文字列、オプション): データベースのパスワード。デフォルトは"demo"です。
    • dsn (文字列、オプション): ODBC データソース名。デフォルトは"Local Virtuoso"です。
  • テーブル情報 (例: TABLE_CAT 、 TABLE_SCHEM 、 TABLE_NAME 、 TABLE_TYPE ) を含む JSON 文字列を返します。
• filter_table_names
  • 名前に特定の部分文字列が含まれるテーブルに関する情報をフィルタリングして返します。
  • 入力パラメータ:
    • q (文字列、必須): テーブル名内で検索する部分文字列。
    • schema (文字列, オプション): テーブルをフィルタリングするためのデータベーススキーマ。デフォルトは接続のデフォルトです。
    • user (文字列、オプション): データベースのユーザー名。デフォルトは"demo"です。
    • password (文字列、オプション): データベースのパスワード。デフォルトは"demo"です。
    • dsn (文字列、オプション): ODBC データソース名。デフォルトは"Local Virtuoso"です。
  • 一致するテーブルの情報を含む JSON 文字列を返します。
• describe_table
  • 特定のテーブルの列に関する詳細情報を取得して返します。
  • 入力パラメータ:
    • schema (文字列、必須): テーブルを含むデータベース スキーマ名。
    • table (文字列、必須): 説明するテーブルの名前。
    • user (文字列、オプション): データベースのユーザー名。デフォルトは"demo"です。
    • password (文字列、オプション): データベースのパスワード。デフォルトは"demo"です。
    • dsn (文字列、オプション): ODBC データソース名。デフォルトは"Local Virtuoso"です。
  • テーブルの列を記述する JSON 文字列を返します (例: COLUMN_NAME 、 TYPE_NAME 、 COLUMN_SIZE 、 IS_NULLABLE )。
• query_database
  • 標準 SQL クエリを実行し、結果を JSON 形式で返します。
  • 入力パラメータ:
    • query (文字列、必須): 実行する SQL クエリ文字列。
    • user (文字列、オプション): データベースのユーザー名。デフォルトは"demo"です。
    • password (文字列、オプション): データベースのパスワード。デフォルトは"demo"です。
    • dsn (文字列、オプション): ODBC データソース名。デフォルトは"Local Virtuoso"です。
  • クエリ結果を JSON 文字列として返します。
• query_database_md
  • 標準 SQL クエリを実行し、Markdown テーブルとしてフォーマットされた結果を返します。
  • 入力パラメータ:
    • query (文字列、必須): 実行する SQL クエリ文字列。
    • user (文字列、オプション): データベースのユーザー名。デフォルトは"demo"です。
    • password (文字列、オプション): データベースのパスワード。デフォルトは"demo"です。
    • dsn (文字列、オプション): ODBC データソース名。デフォルトは"Local Virtuoso"です。
  • クエリ結果を Markdown テーブル文字列として返します。
• query_database_jsonl
  • 標準 SQL クエリを実行し、結果を JSON Lines (JSONL) 形式 (1 行につき 1 つの JSON オブジェクト) で返します。
  • 入力パラメータ:
    • query (文字列、必須): 実行する SQL クエリ文字列。
    • user (文字列、オプション): データベースのユーザー名。デフォルトは"demo"です。
    • password (文字列、オプション): データベースのパスワード。デフォルトは"demo"です。
    • dsn (文字列、オプション): ODBC データソース名。デフォルトは"Local Virtuoso"です。
  • クエリ結果を JSONL 文字列として返します。
• spasql_query
  • SPASQL（SQL/SPARQLハイブリッド）クエリを実行し、結果を返します。これはVirtuoso固有の機能です。
  • 入力パラメータ:
    • query (文字列、必須): SPASQL クエリ文字列。
    • max_rows (数値、オプション): 返される行の最大数。デフォルトは20です。
    • timeout (数値, オプション): クエリのタイムアウト時間（ミリ秒）。デフォルトは30000 、つまり30秒です。
    • user (文字列、オプション): データベースのユーザー名。デフォルトは"demo"です。
    • password (文字列、オプション): データベースのパスワード。デフォルトは"demo"です。
    • dsn (文字列、オプション): ODBC データソース名。デフォルトは"Local Virtuoso"です。
  • 基になるストアド プロシージャ呼び出し (例: Demo.demo.execute_spasql_query ) からの結果を返します。
• sparql_query
  • SPARQLクエリを実行し、結果を返します。これはVirtuoso固有の機能です。
  • 入力パラメータ:
    • query (文字列、必須): SPARQL クエリ文字列。
    • format (文字列、オプション): 希望する結果の形式。デフォルトは'json'です。
    • timeout (数値, オプション): クエリのタイムアウト時間（ミリ秒）。デフォルトは30000 、つまり30秒です。
    • user (文字列、オプション): データベースのユーザー名。デフォルトは"demo"です。
    • password (文字列、オプション): データベースのパスワード。デフォルトは"demo"です。
    • dsn (文字列、オプション): ODBC データソース名。デフォルトは"Local Virtuoso"です。
  • 基礎となる関数呼び出しの結果を返します (例: "UB".dba."sparqlQuery" )。
• virtuoso_support_ai
  • Virtuoso固有のAIアシスタント機能を利用し、プロンプトとオプションのAPIキーを渡します。これはVirtuoso固有の機能です。
  • 入力パラメータ:
    • prompt (文字列、必須): AI 関数のプロンプト テキスト。
    • api_key （文字列、オプション）：AIサービスのAPIキー。デフォルトは"none"です。
    • user (文字列、オプション): データベースのユーザー名。デフォルトは"demo"です。
    • password (文字列、オプション): データベースのパスワード。デフォルトは"demo"です。
    • dsn (文字列、オプション): ODBC データソース名。デフォルトは"Local Virtuoso"です。
  • AI サポート アシスタント関数呼び出しの結果を返します (例: DEMO.DBA.OAI_VIRTUOSO_SUPPORT_AI )。

基本的なインストールテストとトラブルシューティング

MCP インスペクターツール

標準MCPインスペクタツールエディション

1. 次のコマンドを使用して、mcp-server ディレクトリ/フォルダーからインスペクターを起動します。
   ODBCINI=/Library/ODBC/odbc.ini npx -y @modelcontextprotocol/inspector npx tsx ./src/main.ts
2. 「接続」ボタンをクリックし、「ツール」タブをクリックして開始します。

OpenLink MCP インスペクターツールエディション

これは、この MCP サーバーでの使用に関連する JSON 処理のバグ修正を含む標準エディションのフォークです。

1. 走る
   git clone git@github.com:OpenLinkSoftware/inspector.git cd inspector
2. 走る
   npm run start
3. http://localhost:6274から MCP Inspectors UI のArguments入力フィールドに次の値を入力します。
   tsx /path/to/mcp-odbc-server/src/main.ts
4. 指定されたMCPサーバーとのセッションを初期化するには、 Connectボタンをクリックします。

Apple Silicon (ARM64) と MCP ODBC サーバの互換性に関する問題

Node x86_64とarm64の競合問題

nodeの arm64 エディションではなく x86_64 エディションが使用されている可能性がありますが、ODBC ブリッジと MCP サーバーは arm64 ベースのコンポーネントです。

この問題は、次の手順を実行することで解決できます。

1. 次のコマンドを実行して、x86_64 エディションのnodeをアンインストールします。
   nvm uninstall 21.1.0
2. 次のコマンドを実行して、現在のシェルが arm64 モードになっていることを確認します。
   arch
   • x86_64 が返された場合は、次のコマンドを実行してアクティブ モードを変更します。
     arch arm64
3. 次のコマンドを実行して、arm64 エディションのnodeをインストールします。
   nvm install 21.1.0

ノードと ODBC ブリッジ層の非互換性

Apple Silicon マシンで Model Context Protocol (MCP) ODBC サーバーを使用しようとすると、アーキテクチャの不一致エラーが発生する場合があります。これは、Node.js ODBC ネイティブモジュール ( odbc.node ) が ARM64 アーキテクチャ用にコンパイルされているにもかかわらず、unixODBC ランタイムの x86_64 ベースエディションがロードされているためです。

一般的なエラーメッセージ:

この問題は、次の手順を実行することで解決できます。

1. Node.js が ARM64 モードで実行されていることを確認します。
   node -p "process.arch" # Should output: `arm64`
2. ARM64 用の unixODBC をインストールします。
   # 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. ARM64 用の Node.js ODBC モジュールを再構築します。
   # 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. モジュールが ARM64 になっていることを確認します。
   file node_modules/odbc/lib/bindings/napi-v8/odbc.node # Should show "arm64" instead of "x86_64"

要点

• unixODBCとNode.js ODBCモジュールはどちらもARM64互換である必要があります。
• 環境変数（ export npm_config_arch=arm64 ）を使用する方が、npm configコマンドよりも信頼性が高い
• 常にfileコマンドまたはnode -p "process.arch"でアーキテクチャを確認してください。
• Apple SiliconでHomebrewを使用する場合、コマンドの前にarch -arm64を付けてARM64バイナリの使用を強制することができます。

MCP アプリケーションの使用

クロードデスクトップ構成

この構成ファイルのパスは、 ~{username}/Library/Application Support/Claude/claude_desktop_config.jsonです。

クロードのデスクトップ使用状況

1. アプリケーションを起動します。
2. 設定 | 開発者ユーザー インターフェースから (上記の) 構成を適用します。
3. データ ソース名 (DSN) への ODBC 接続が機能していることを確認します。
4. クエリの実行を要求するプロンプトを表示します。例:
   Execute the following query: SELECT TOP * from Demo..Customers

Cline (Visual Studio 拡張機能) の構成

この設定ファイルのパスは次のとおりです: ~{username}/Library/Application\ Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Cline (Visual Studio 拡張機能) の使用法

1. Shift + Command + P を押してコマンドパレットを開きます。
2. Clineと入力します。
3. 選択: Cline View。VSCode サイドバーに Cline UI が開きます。
4. 4 つの四角形のアイコンを使用して、MCP サーバーをインストールおよび構成するための UI にアクセスします。
5. Cline Config (上記) を適用します。
6. 拡張機能のメイン UI に戻り、次のプロンプトの処理を要求する新しいタスクを開始します。
   "Execute the following query: SELECT TOP 5 * from Demo..Customers"

カーソルの設定

設定ギアを使用して、 mcp servers登録および構成するための MCP メニュー項目を含む構成メニューを開きます。

カーソルの使用

1. チャット インターフェイスを開くには、 Command + IまたはControl + Iキーの組み合わせを使用します。
2. UI の左下にあるドロップダウンからAgentを選択します。デフォルトはAskです。
3. パターン@odbc {rest-of-prompt}を使用して、 mcp-server for odbcの使用を限定してプロンプトを入力します。
4. 「承認」をクリックしてプロンプトを実行します。

関連している

• MCP Inspector の使用法スクリーンキャスト
• Claude デスクトップの基本的な使用方法のスクリーンキャスト
• Cline Visual Studio Code 拡張機能の基本的な使用方法のスクリーンキャスト
• 基本的なカーソルエディターの使い方のスクリーンキャスト