mcp-odbc-server

ODBC 用 OpenLink MCP サーバー

このドキュメントでは、Model Context Protocol（MCP）向けの汎用 ODBC サーバー（mcp-odbc サーバー）のセットアップと使用方法を説明します。このサーバーは、特定の ODBC コネクター（ODBC ドライバーとも呼ばれます）用に設定されたデータソース名を介して、LLM が ODBC でアクセス可能なデータソースに透過的にアクセスできるよう開発されました。

サーバーの実装

このODBC 用 MCP サーバーは、node-odbc を基盤とした小規模な TypeScript レイヤーです。node.js（具体的には TypeScript 用の npx）を介して、ホストシステムのローカル 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）を使用する場合は対象の LLM API キー（API_KEY）を設定してください。

API_KEY=sk-xxx
ODBC_DSN=Local Virtuoso
ODBC_USER=dba
ODBC_PASSWORD=dba
ODBCINI=/Library/ODBC/odbc.ini 

使用方法

ツール

インストールが正常に完了すると、以下のツールを MCP クライアントアプリケーションから利用できるようになります。

概要

name	description
get_schemas	接続先のデータベース管理システム（DBMS）からアクセスできるデータベーススキーマを一覧表示します。
get_tables	選択したデータベーススキーマに属するテーブルを一覧表示します。
describe_table	指定したデータベーススキーマに属するテーブルの説明を返します。列名、データ型、NULL の処理、自動インクリメント、主キー、外部キーに関する情報が含まれます。
filter_table_names	入力フィールド q の部分文字列パターンに基づき、選択したデータベーススキーマに属するテーブルを一覧表示します。
query_database	SQL クエリを実行し、JSON Lines（JSONL）形式で結果を返します。
execute_query	SQL クエリを実行し、JSON Lines（JSONL）形式で結果を返します。
execute_query_md	SQL クエリを実行し、Markdown テーブル形式で結果を返します。
spasql_query	SPASQL クエリを実行し、結果を返します。
sparql_query	SPARQL クエリを実行し、結果を返します。
virtuoso_support_ai	Virtuoso Support アシスタント／エージェントと対話します。Virtuoso 固有の機能で、LLM との対話に使用します。

詳細

• get_schemas

  • 接続先データベースからすべてのスキーマ名を取得し、一覧として返します。
  • 入力パラメーター：
    • user（文字列、任意）：データベースのユーザー名です。デフォルトは "demo" です。
    • password（文字列、任意）：データベースのパスワードです。デフォルトは "demo" です。
    • dsn（文字列、任意）：ODBC データソース名です。デフォルトは "Local Virtuoso" です。
  • スキーマ名の JSON 文字列配列を返します。

• get_tables

  • 指定したスキーマ内のテーブル情報を含むリストを取得して返します。スキーマが指定されていない場合は、接続のデフォルトスキーマを使用します。
  • 入力パラメーター：
    • schema (string, optional)：テーブルを絞り込むデータベーススキーマです。デフォルトは接続のデフォルトスキーマです。
    • user (string, optional)：データベースのユーザー名です。デフォルトは "demo" です。
    • password (string, optional)：データベースのパスワードです。デフォルトは "demo" です。
    • dsn (string, optional)：ODBC データソース名です。デフォルトは "Local Virtuoso" です。
  • テーブル情報（例：TABLE_CAT、TABLE_SCHEM、TABLE_NAME、TABLE_TYPE）を含む JSON 文字列を返します。

• filter_table_names

  • 名前に特定の部分文字列を含むテーブルの情報を絞り込んで返します。
  • 入力パラメーター：
    • q (string, required)：テーブル名に含まれるかを検索する部分文字列です。
    • schema (string, optional)：テーブルを絞り込むデータベーススキーマです。デフォルトは接続のデフォルトスキーマです。
    • user (string, optional)：データベースのユーザー名です。デフォルトは "demo" です。
    • password (string, optional)：データベースのパスワードです。デフォルトは "demo" です。
    • dsn (string, optional)：ODBC データソース名です。デフォルトは "Local Virtuoso" です。
  • 条件に一致するテーブルの情報を含む JSON 文字列を返します。

• describe_table

  • 特定のテーブルの列に関する詳細情報を取得して返します。
  • 入力パラメーター：
    • schema (string, required)：テーブルを含むデータベーススキーマの名前です。
    • table (string, required)：説明するテーブルの名前です。
    • user (string, optional)：データベースのユーザー名です。デフォルトは "demo" です。
    • password (string, optional)：データベースのパスワードです。デフォルトは "demo" です。
    • dsn (string, optional)：ODBC データソース名です。デフォルトは "Local Virtuoso" です。
  • テーブルの列を説明する JSON 文字列（例：COLUMN_NAME、TYPE_NAME、COLUMN_SIZE、IS_NULLABLE）を返します。

• query_database

  • 標準的な SQL クエリを実行し、結果を JSON 形式で返します。
  • 入力パラメーター：
    • query (string, required)：実行する SQL クエリ文字列です。
    • user (string, optional)：データベースのユーザー名です。デフォルトは "demo" です。
    • password (string, optional)：データベースのパスワードです。デフォルトは "demo" です。
    • dsn (string, optional)：ODBC データソース名です。デフォルトは "Local Virtuoso" です。
  • クエリ結果を JSON 文字列として返します。

• query_database_md

  • 標準的な SQL クエリを実行し、結果を Markdown テーブル形式で返します。
  • 入力パラメーター：
    • query (string, required)：実行する SQL クエリ文字列です。
    • user (string, optional)：データベースのユーザー名です。デフォルトは "demo" です。
    • password (string, optional)：データベースのパスワードです。デフォルトは "demo" です。
    • dsn (string, optional)：ODBC データソース名です。デフォルトは "Local Virtuoso" です。
  • クエリ結果を Markdown テーブル文字列として返します。

• query_database_jsonl

  • 標準的な SQL クエリを実行し、結果を JSON Lines（JSONL）形式（1 行につき JSON オブジェクト 1 つ）で返します。
  • 入力パラメーター：
    • query (string, required)：実行する SQL クエリ文字列です。
    • user (string, optional)：データベースのユーザー名です。デフォルトは "demo" です。
    • password (string, optional)：データベースのパスワードです。デフォルトは "demo" です。
    • dsn (string, optional)：ODBC データソース名です。デフォルトは "Local Virtuoso" です。
  • クエリ結果を JSONL 文字列として返します。

• spasql_query

  • SPASQL（SQL/SPARQL ハイブリッド）クエリを実行し、結果を返します。これは Virtuoso 固有の機能です。
  • 入力パラメーター：
    • query（string、必須）：SPASQL クエリ文字列です。
    • max_rows（number、任意）：返す行数の最大値です。既定値は 20 です。
    • timeout（number、任意）：クエリのタイムアウト時間（ミリ秒）です。既定値は 30000（30 秒）です。
    • user（string、任意）：データベースのユーザー名です。既定値は "demo" です。
    • password（string、任意）：データベースのパスワードです。既定値は "demo" です。
    • dsn（string、任意）：ODBC データソース名です。既定値は "Local Virtuoso" です。
  • 内部のストアドプロシージャ呼び出し（例：Demo.demo.execute_spasql_query）から結果を返します。

• sparql_query

  • SPARQL クエリを実行し、結果を返します。これは Virtuoso 固有の機能です。
  • 入力パラメーター：
    • query（string、必須）：SPARQL クエリ文字列です。
    • format（string、任意）：希望する結果形式です。既定値は 'json' です。
    • timeout（number、任意）：クエリのタイムアウト時間（ミリ秒）です。既定値は 30000（30 秒）です。
    • user（string、任意）：データベースのユーザー名です。既定値は "demo" です。
    • password（string、任意）：データベースのパスワードです。既定値は "demo" です。
    • dsn（string、任意）：ODBC データソース名です。既定値は "Local Virtuoso" です。
  • 内部の関数呼び出し（例："UB".dba."sparqlQuery"）から結果を返します。

• virtuoso_support_ai

  • プロンプトと任意の API キーを渡して、Virtuoso 固有の AI アシスタント関数を利用します。これは Virtuoso 固有の機能です。
  • 入力パラメーター：
    • prompt（string、必須）：AI 関数に渡すプロンプトテキストです。
    • api_key（string、任意）：AI サービスの API キーです。既定値は "none" です。
    • user（string、任意）：データベースのユーザー名です。既定値は "demo" です。
    • password（string、任意）：データベースのパスワードです。既定値は "demo" です。
    • dsn（string、任意）：ODBC データソース名です。既定値は "Local Virtuoso" です。
  • AI Support Assistant 関数の呼び出し（例：DEMO.DBA.OAI_VIRTUOSO_SUPPORT_AI）から結果を返します。

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

MCP Inspector ツール

標準版 MCP Inspector ツール

1. 次のコマンドを使って、mcp-server ディレクトリ／フォルダーからインスペクターを起動します：

   ODBCINI=/Library/ODBC/odbc.ini npx -y @modelcontextprotocol/inspector npx tsx ./src/main.ts 
   

2. 「Connect」ボタンをクリックし、次に「Tools」タブをクリックして開始します。

   

OpenLink 版 MCP Inspector ツール

この標準版のフォークには、この MCP サーバーでの使用に関連する JSON 処理のバグ修正が含まれています。

1. 実行

   git clone [email protected]:OpenLinkSoftware/inspector.git
   cd inspector
   

2. 実行

   npm run start
   

3. http://localhost:6274 の MCP Inspector UI にある Arguments 入力フィールドに、次の値を入力します

   tsx /path/to/mcp-odbc-server/src/main.ts
   

4. Connect ボタンをクリックして、指定した MCP サーバーとのセッションを初期化します

Apple Silicon（ARM64）での MCP ODBC サーバーの互換性に関する問題

Node の x86_64 と arm64 の競合

x86_64 版の node がインストールされている可能性がありますが、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
   

Node と ODBC のブリッジ層の非互換性

Apple Silicon 搭載マシンで Model Context Protocol（MCP）ODBC サーバーを使用しようとすると、アーキテクチャの不一致エラーが発生することがあります。これは、Node.js ODBC ネイティブモジュール（odbc.node）が ARM64 アーキテクチャ向けにコンパイルされている一方で、x86_64 ベースの unixODBC ランタイムが読み込まれるために発生します。

典型的なエラーメッセージ：

Error: dlopen(...odbc.node, 0x0001): tried: '...odbc.node' (mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64e' or 'arm64'))

以下の手順でこの問題を解決できます。

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 アプリケーションの使用方法

Claude Desktop の設定

設定ファイルのパスは次のとおりです：~{username}/Library/Application Support/Claude/claude_desktop_config.json。

{
    "mcpServers": {
        "ODBC": {
            "command": "/path/to/.nvm/versions/node/v21.1.0/bin/node",
            "args": [
                "/path/to/mcp-odbc-server/node_modules/.bin/tsx",
                "/path/to/mcp-odbc-server/src/main.ts"
            ],
            "env": {
                "ODBCINI": "/Library/ODBC/odbc.ini",
                "NODE_VERSION": "v21.1.0",
                "PATH": "~/.nvm/versions/node/v21.1.0/bin:${PATH}"
            },
            "disabled": false,
            "autoApprove": []
        }
    }
}

Claude Desktop の使用方法

1. アプリケーションを起動します。

2. 設定（上記）を「設定」｜「開発者」ユーザーインターフェイスから適用します。

3. Data Source Name（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

{
  "mcpServers": {
    "ODBC": {
      "command": "/path/to/.nvm/versions/node/v21.1.0/bin/node",
      "args": [
        "/path/to/mcp-odbc-server/node_modules/.bin/tsx",
        "/path/to/mcp-odbc-server/src/main.ts"
      ],
      "env": {
        "ODBCINI": "/Library/ODBC/odbc.ini",
        "NODE_VERSION": "v21.1.0",
        "PATH": "/path/to/.nvm/versions/node/v21.1.0/bin:${PATH}"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Cline（Visual Studio 拡張機能）の使用方法

1. Shift+Command+P を押してコマンドパレットを開きます。

2. Cline と入力します。

3. Cline View を選択すると、VSCode のサイドバーに Cline UI が開きます。

4. 四つの四角形のアイコンを使って、MCP サーバーのインストールと設定用の UI にアクセスします。

5. Cline の設定（上記）を適用します。

6. 拡張機能のメイン UI に戻り、次のプロンプトの処理を求める新しいタスクを開始します。

   "Execute the following query: SELECT TOP 5 * from Demo..Customers"
   

   

Cursor の設定

設定ギアを使って設定メニューを開きます。このメニューには、mcp servers の登録と設定を行う MCP メニュー項目があります。

Cursor の使用方法

1. Command+I または Control+I のキーの組み合わせを使って、チャットインターフェイスを開きます。

2. UI の左下にあるドロップダウンから Agent を選択します。デフォルトは Ask です。

3. 次のパターンを使い、mcp-server for odbc の使用を指定してプロンプトを入力します：@odbc {rest-of-prompt}。

4. 「Accept」をクリックしてプロンプトを実行します。

   

関連情報

• MCP Inspector の使用方法の画面録画
• Claude Desktop の基本的な使用方法の画面録画
• Cline Visual Studio Code 拡張機能の基本的な使用方法の画面録画
• Cursor Editor の基本的な使用方法の画面録画