MCP Server ODBC via SQLAlchemy

---

SQLAlchemy 経由の MCP Server ODBC

FastAPI、pyodbc、SQLAlchemyで構築された、ODBC 用の軽量な MCP（Model Context Protocol）サーバーです。このサーバーは、Virtuoso DBMS および SQLAlchemy プロバイダーを実装するその他の 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
   

6. SQLAlchemy URL のバインディング：次の形式を使用します：

   virtuoso+pyodbc://user:password@VOS
   

---

インストール

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

git clone https://github.com/OpenLinkSoftware/mcp-sqlalchemy-server.git
cd mcp-sqlalchemy-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-sqlalchemy-server", "run", "mcp-sqlalchemy-server"],
      "env": {
        "ODBC_DSN": "dsn_name",
        "ODBC_USER": "username",
        "ODBC_PASSWORD": "password",
        "API_KEY": "sk-xxx"
      }
    }
  }
}

---

使用方法

データベース管理システム（DBMS）の接続 URL

この mcp-server を使用して接続をテストした DBMS システム向けの pyodbc URL の例を示します。

データベース	URL 形式
Virtuoso DBMS	virtuoso+pyodbc://user:password@ODBC_DSN
PostgreSQL	postgresql://user:password@localhost/dbname
MySQL	mysql+pymysql://user:password@localhost/dbname
SQLite	sqlite:///path/to/database.db
接続後は、Claude の AI 機能を活用して、WhatsApp の会話を通じて Claude と WhatsApp の連絡先についてやり取りできます。

提供されるツール

概要

名前	説明
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_sparql_query	SPARQL クエリを実行し、結果を返します。
podbc_virtuoso_support_ai	Virtuoso サポートアシスタント／エージェントとやり取りします。これは、LLM とやり取りするための Virtuoso 固有の機能です。

詳細な説明

• podbc_get_schemas

  • 接続中のデータベースからすべてのスキーマ名を取得して返します。
  • 入力パラメーター：
    • user (string, optional)：データベースのユーザー名です。デフォルトは "demo" です。
    • password (string, optional)：データベースのパスワードです。デフォルトは "demo" です。
    • dsn (string, optional)：ODBC データソース名です。デフォルトは "Local Virtuoso" です。
  • スキーマ名を含む JSON 文字列配列を返します。

• podbc_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 文字列を返します。

• podbc_filter_table_names

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

• podbc_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）。

• podbc_query_database

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

• podbc_query_database_md

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

• podbc_query_database_jsonl

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

• podbc_spasql_query

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

• podbc_sparql_query

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

• podbc_virtuoso_support_ai

  • Virtuoso 固有の AI アシスタント関数を使用し、プロンプトと任意の API キーを渡します。これは Virtuoso 固有の機能です。
  • 入力パラメーター：
    • prompt（文字列、必須）：AI 関数に渡すプロンプトテキストです。
    • api_key（文字列、任意）：AI サービスの API キーです。デフォルトは "none" です。
    • user（文字列、任意）：データベースのユーザー名です。デフォルトは "demo" です。
    • password（文字列、任意）：データベースのパスワードです。デフォルトは "demo" です。
    • dsn（文字列、任意）：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-sqlalchemy-server run mcp-sqlalchemy-server
   

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