Universal Sql MCP Server

🚀 Universal SQL MCP Server

Universal SQL MCP Serverは、複数のSQLデータベースエンジンへの安全なアクセスを提供するModel Context Protocol (MCP)サーバーです。このサーバーを使用すると、AIアシスタントやその他のMCPクライアントが、標準化されたインターフェースを介して様々なSQLデータベースとやり取りできます。

📦 インストール

1. リポジトリをクローン

git clone <repository-url>
cd gen-http-sql-mcp

2. 依存関係をインストール

# Using pip
pip install fastmcp mysql-connector-python psycopg2-binary pyodbc sqlalchemy python-dotenv

# Or using uv
uv sync

3. （オプション）必要に応じてデータベース固有のドライバーをインストール

# For MySQL only
pip install fastmcp mysql-connector-python python-dotenv

# For PostgreSQL only  
pip install fastmcp psycopg2-binary python-dotenv

# For SQLite only (no additional drivers needed)
pip install fastmcp python-dotenv

# For SQL Server only
pip install fastmcp pyodbc python-dotenv

✨ 主な機能

• 複数データベース対応：MySQL、PostgreSQL、SQLite、SQL Serverと互換性があります。
• データベーススキーマ検査：すべてのテーブル、列、インデックス、制約に関する包括的な情報を取得できます。
• 安全なクエリ実行：組み込みのセキュリティ制限を持つSELECTクエリを実行できます。
• 制御された書き込み操作：適切なセキュリティ制御を持つINSERTおよびUPDATE操作を実行できます。
• 接続テスト：データベースの接続と構成を検証できます。
• 環境ベースの構成：環境変数を通じた安全な構成が可能です。
• 包括的なロギング：監視とデバッグのための詳細なロギングが提供されます。
• データベース固有の最適化：各データベースエンジンに合わせたクエリと機能が用意されています。

💻 使用例

基本的な使用法

デモの試し方（SQLite）

Universal SQL MCP Serverをすぐに試す最速の方法は以下の通りです。

# Clone the repository
git clone <repository-url>
cd gen-http-sql-mcp

# Install dependencies
pip install fastmcp mysql-connector-python psycopg2-binary pyodbc sqlalchemy python-dotenv

# Run the demo (creates a SQLite database with sample data)
python demo.py

# Start the MCP server
python main.py

このデモでは、サンプルのユーザーと注文データを持つSQLiteデータベースが作成され、すべてのMCPツールがデモされます。

高度な使用法

サーバーの起動

uv run python main.py

サーバーは以下の手順で起動します。

1. 環境変数から構成を読み込みます。
2. データベース接続をテストします。
3. MCPサーバーを起動し、リクエストを待ち受けます。

MCPクライアントとの使用

このサーバーはModel Context Protocolを実装しており、MCP互換のクライアントと一緒に使用できます。サーバーは、MCPクライアントが呼び出せる3つのツールを提供します。

ツール呼び出しの例

1. データベーススキーマの取得

{
  "method": "tools/call",
  "params": {
    "name": "get_database_schema"
  }
}

2. SQLクエリの実行（すべてのデータベースタイプで動作します）

{
  "method": "tools/call",
  "params": {
    "name": "execute_sql_query",
    "arguments": {
      "sql_query": "SELECT * FROM users LIMIT 10"
    }
  }
}

3. 書き込み操作の実行（すべてのデータベースタイプで動作します）

{
  "method": "tools/call",
  "params": {
    "name": "execute_write_operation",
    "arguments": {
      "sql_query": "INSERT INTO users (name, email) VALUES ('John Doe', 'john@example.com')"
    }
  }
}

4. 接続テスト

{
  "method": "tools/call",
  "params": {
    "name": "test_database_connection"
  }
}

データベース固有のクエリ例

RETURNING句を使用したPostgreSQL

INSERT INTO users (name, email) VALUES ('Jane Doe', 'jane@example.com') RETURNING id;

オートインクリメントを使用したSQLite

INSERT INTO users (name, email) VALUES ('Bob Smith', 'bob@example.com');

OUTPUT句を使用したSQL Server

INSERT INTO users (name, email) OUTPUT INSERTED.id VALUES ('Alice Johnson', 'alice@example.com');

📚 詳細ドキュメント

設定

1. 環境ファイルのコピー

cp .env.example .env

2. .envファイルを編集してデータベースの資格情報を設定

MySQL構成

DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database

PostgreSQL構成

DB_TYPE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database

SQLite構成

DB_TYPE=sqlite
DB_NAME=/path/to/your/database.db
# Note: SQLite doesn't require host, port, user, or password

SQL Server構成

DB_TYPE=sqlserver
DB_HOST=localhost
DB_PORT=1433
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database
DB_DRIVER=ODBC Driver 17 for SQL Server

共通のオプション設定

# Optional: Connection pool settings (not applicable for SQLite)
DB_POOL_SIZE=5
DB_MAX_OVERFLOW=10

# Optional: Connection timeout settings (in seconds)
DB_CONNECT_TIMEOUT=10
DB_READ_TIMEOUT=30
DB_WRITE_TIMEOUT=30

# Optional: Enable write operations (INSERT/UPDATE) - set to true to enable
ENABLE_WRITE_OPERATIONS=false

設定オプション

• DB_TYPE：使用するデータベースエンジンを指定します。

  • mysql：MySQLデータベース（mysql-connector-pythonが必要）
  • postgresql：PostgreSQLデータベース（psycopg2-binaryが必要）
  • sqlite：SQLiteデータベース（Pythonに組み込まれたサポート）
  • sqlserver：SQL Serverデータベース（pyodbcが必要）

• ENABLE_WRITE_OPERATIONS：execute_write_operationツールの使用可否を制御します。

  • false（デフォルト）：読み取り専用操作のみが許可されます（SELECTクエリのみ）。
  • true：execute_write_operationツールを通じてINSERTおよびUPDATE操作が可能になります。
  • セキュリティ上の理由から、DELETE、DROP、TRUNCATE、ALTER、CREATE操作は常にブロックされます。

• リクエストロギングの構成

  • ENABLE_REQUEST_LOGGING：基本的なリクエストロギングを有効にします（デフォルトでtrue）。
  • ENABLE_DETAILED_REQUEST_LOGGING：ヘッダーとペイロードを含む詳細なリクエストロギングを有効にします（デフォルトでfalse）。
  • REQUEST_LOG_LEVEL：リクエストロギングのログレベル（デフォルトでINFO）。
  • MAX_PAYLOAD_LOG_LENGTH：ログに記録されるペイロードの最大長（デフォルトで2000）。
  • LOG_LEVEL：アプリケーション全体のログレベル（デフォルトでINFO）。

データベース固有の注意事項

• SQLite：DB_NAME（ファイルパス）のみが必要です。接続プール設定は無視されます。
• SQL Server：追加のODBCドライバーのインストールとDB_DRIVERの指定が必要な場合があります。
• PostgreSQL：最適なパフォーマンスと互換性のためにpsycopg2-binaryを使用します。
• MySQL：公式のmysql-connector-pythonドライバーを使用します。

セキュリティ機能

• 制御された書き込みアクセス：書き込み操作ではINSERTとUPDATE操作のみが許可されます。
• 読み取りアクセス：SELECTクエリは専用のツールを通じて利用できます。
• クエリ検証：危険なSQLキーワード（DELETE、DROP、TRUNCATEなど）はブロックされます。
• 操作の分離：読み取りと書き込み操作は別々のツールで処理されます。
• 環境変数：機密性の高い構成は環境変数に保存されます。
• 接続管理：タイムアウトとクリーンアップを伴う適切な接続処理が行われます。
• トランザクションの安全性：書き込み操作には自動コミットとエラーハンドリングが含まれています。

プロジェクト構造

gen-http-sql-mcp/
├── main.py              # Main server entry point
├── database.py          # Universal database connection and management
├── tools.py             # MCP tools implementation
├── .env.example         # Environment configuration template
├── pyproject.toml       # Project dependencies and metadata
└── README.md           # This file

データベースエンジンのサポート詳細

MySQL

• テーブルコメント、列詳細、インデックス情報を含む完全なスキーマイントロスペクション
• 接続プールとタイムアウト構成をサポート
• 最適な互換性のためにmysql-connector-pythonを使用

PostgreSQL

• テーブルと列のコメントを含む包括的なスキーマ情報
• 高度なインデックス情報と制約詳細
• 高性能のためにpsycopg2-binaryを使用

SQLite

• 完全なテーブルと列情報
• インデックス詳細と主キー情報
• 開発、テスト、軽量アプリケーションに最適
• 追加のドライバーインストールは不要

SQL Server

• 完全なテーブルと列のスキーマ情報
• WindowsとSQL Serverの両方の認証をサポート
• pyodbcを介したODBC接続を使用
• 構成可能なODBCドライバー選択

依存関係

• fastmcp：MCPサーバーを構築するためのFastMCPフレームワーク
• mysql-connector-python：Python用の公式MySQLドライバー
• psycopg2-binary：Python用のPostgreSQLアダプター
• pyodbc：SQL Server用のODBCデータベース接続
• sqlalchemy：SQLツールキットとオブジェクトリレーショナルマッピングライブラリ
• python-dotenv：環境変数の読み込み
• sqlite3：Pythonに組み込まれたSQLiteサポート（追加のインストール不要）

エラーハンドリング

サーバーには包括的なエラーハンドリングが組み込まれています。

• データベース接続エラーはログに記録され、報告されます。
• 無効なSQLクエリは明確なエラーメッセージで拒否されます。
• 構成の検証により、必要なパラメーターが存在することが保証されます。
• 中断時にはグレースフルシャットダウンが行われます。

ロギング

サーバーは包括的なロギング機能を提供します。

基本的なロギング

• 接続状態とデータベース情報
• クエリ実行結果とパフォーマンス
• コンテキスト付きのエラーメッセージ
• サーバーの起動とシャットダウンイベント

リクエストロギング

サーバーには、クライアント接続問題のデバッグを支援する高度なリクエストロギングミドルウェアが含まれています。

シンプルなリクエストロギング（デフォルト）

# Enabled by default, shows basic request information
ENABLE_REQUEST_LOGGING=true

詳細なリクエストロギング（デバッグモード）

# Enable detailed logging with headers and payloads
ENABLE_DETAILED_REQUEST_LOGGING=true
REQUEST_LOG_LEVEL=DEBUG
MAX_PAYLOAD_LOG_LENGTH=5000
LOG_LEVEL=DEBUG

Dockerデバッグ環境

クライアント接続問題をデバッグするには、デバッグ環境を使用します。

# Start debug environment with detailed logging
make debug

# View debug logs
make logs-debug

# View only MCP server debug logs
make logs-debug-mcp

デバッグ環境では以下が有効になります。

• 詳細なリクエスト/レスポンスロギング
• HTTPヘッダーのロギング
• リクエストペイロードのロギング
• レスポンスペイロードのロギング
• 実行タイミング
• クライアント情報の追跡

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細についてはLICENSEファイルを参照してください。

サポート

問題や質問がある場合は以下の手順を試してください。

1. エラーメッセージをログで確認します。
2. データベースの構成を確認します。
3. データベースサーバーにアクセス可能であることを確認します。
4. リポジトリに問題を登録します。