MCP Server ODBC via PyODBC

---

PyODBC 経由の ODBC 用 OpenLink MCP Server

FastAPI と pyodbc で構築された、ODBC 用の軽量な MCP（Model Context Protocol）サーバーです。このサーバーは Virtuoso DBMS と、ODBC ドライバーを備えたその他すべての DBMS バックエンドに対応しています。

---

機能

• スキーマの取得：接続先のデータベースからすべてのスキーマ名を取得して一覧表示します。
• テーブルの取得：特定のスキーマまたはすべてのスキーマのテーブル情報を取得します。
• テーブルの説明：次の情報を含む、テーブル構造の詳細な説明を生成します。
  • 列名とデータ型
  • NULL 許容属性
  • 主キーと外部キー
• テーブルの検索：名前の部分文字列に基づいてテーブルを絞り込み、取得します。
• ストアドプロシージャの実行：Virtuoso に接続している場合、ストアドプロシージャを実行して結果を取得します。
• クエリの実行：
  • JSONL 結果形式：構造化された応答に最適です。
  • Markdown テーブル形式：レポートや視覚化に最適です。

---

前提条件

1. uv のインストール：

   pip install uv
   

   または Homebrew を使用します：

   brew install uv
   

2. unixODBC ランタイム環境の確認：

3. odbcinst -j を実行して、インストール設定（主要な INI ファイルの場所など）を確認します。

4. odbcinst -q -s を実行して、利用可能なデータソース名を一覧表示します。

5. ODBC DSN の設定：対象のデータベースに合わせて、ODBC データソース名（通常は ~/.odbc.ini 内）を設定します。Virtuoso DBMS の設定例：

   [VOS]
   Description = OpenLink Virtuoso
   Driver = /path/to/virtodbcu_r.so
   Database = Demo
   Address = localhost:1111
   WideAsUTF16 = Yes
   

---

インストール

このリポジトリをクローンします：

git clone https://github.com/OpenLinkSoftware/mcp-pyodbc-server.git
cd mcp-pyodbc-server

環境変数

デフォルト値を上書きして、任意の設定に合わせて .env を更新します。

ODBC_DSN=VOS
ODBC_USER=dba
ODBC_PASSWORD=dba
API_KEY=xxx

---

設定

Claude Desktop のユーザー向け：

次の内容を claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "my_database": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-pyodbc-server", "run", "mcp-pyodbc-server"],
      "env": {
        "ODBC_DSN": "dsn_name",
        "ODBC_USER": "username",
        "ODBC_PASSWORD": "password",
        "API_KEY": "sk-xxx"
      }
    }
  }
}

---

使用方法

提供されるツール

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

概要

name	description
podbc_get_schemas	接続先のデータベース管理システム（DBMS）からアクセス可能なデータベーススキーマを一覧表示します。
podbc_get_tables	選択したデータベーススキーマに関連付けられたテーブルを一覧表示します。
podbc_describe_table	指定したデータベーススキーマに関連付けられたテーブルの説明を返します。列名、データ型、NULL の扱い、自動インクリメント、主キー、外部キーに関する情報が含まれます
podbc_filter_table_names	選択したデータベーススキーマに関連付けられたテーブルを、入力フィールド q の部分文字列パターンに基づいて一覧表示します。
podbc_query_database	SQL クエリを実行し、結果を JSONL 形式で返します。
podbc_execute_query	SQL クエリを実行し、結果を JSONL 形式で返します。
podbc_execute_query_md	SQL クエリを実行し、結果を Markdown テーブル形式で返します。
podbc_spasql_query	SPASQL クエリを実行し、結果を返します。
podbc_virtuoso_support_ai	Virtuoso Support Assistant/Agent とやり取りします。これは、LLM とやり取りするための Virtuoso 固有の機能です。

詳細な説明

• podbc_get_schemas

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

• podbc_get_tables

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

• podbc_filter_table_names

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

• podbc_describe_table

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

• podbc_query_database

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

• podbc_query_database_md

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

• podbc_query_database_jsonl

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

• podbc_spasql_query

  • SPASQL（SQL／SPARQL ハイブリッド）クエリを実行し、結果を返します。これは Virtuoso 固有の機能です。
  • 入力パラメーター：
    • query（string、必須）：SPASQL クエリ文字列。
    • max_rows（number、省略可）：返す行数の上限。デフォルトは 20 です。
    • timeout（number、省略可）：クエリのタイムアウト時間（ミリ秒）。デフォルトは 30000 です。
    • user（string、省略可）：データベースのユーザー名。デフォルトは "demo" です。
    • password（string、省略可）：データベースのパスワード。デフォルトは "demo" です。
    • dsn（string、省略可）：ODBC データソース名。デフォルトは "Local Virtuoso" です。
  • 基盤となるストアドプロシージャの呼び出し結果を返します（例：Demo.demo.execute_spasql_query）。

• podbc_virtuoso_support_ai

  • Virtuoso 固有の AI アシスタント機能を利用し、プロンプトと任意の API キーを渡します。これは 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）。

---

トラブルシューティング

トラブルシューティングを簡単にするには：

1. MCP Inspector をインストールします：

   npm install -g @modelcontextprotocol/inspector
   

2. Inspector を起動します：

   npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-pyodbc-server run mcp-pyodbc-server
   

表示された URL にアクセスして、サーバーとのやり取りをトラブルシューティングします。