Text To Sql MCP Server

🚀 Text-to-SQL MCP サーバー

このサービスは FastMCP フレームワークに基づいた安全なデータベースクエリサービスで、データベースのクエリと分析に利用できます。

🚀 クイックスタート

本プロジェクトは MCP (Model Context Protocol) サーバーで、安全なデータベースクエリサービスを提供することを目的としています。FastMCP フレームワークを基に構築され、MySQL データベースへの接続をサポートし、完全な権限管理とセキュリティ制御メカニズムを備えています。

✨ 主な機能

• データベース接続管理: 安全な MySQL データベース接続とクエリ
• 権限認証: RSA 鍵ペアに基づく Bearer Token 認証
• 安全なクエリ: SQL インジェクションや危険な操作を防止するセキュリティチェック
• テーブル構造クエリ: データベースのテーブルリストとテーブル構造情報の取得
• SQL 実行: 安全な SQL クエリの実行、結果の制限をサポート
• ヘルスチェック: サービスの状態監視
• 権限管理: 細かい粒度の権限制御

🛠️ 技術スタック

• Python 3.x: 主要なプログラミング言語
• FastMCP: MCP サーバーフレームワーク
• MySQL: データベースシステム
• uvicorn: ASGI サーバー
• python-dotenv: 環境変数管理

📦 インストール

pip install -r requirements.txt

依存パッケージの説明

python >=3.10

• fastmcp==2.10.6: MCP サーバーフレームワーク
• python-dotenv==1.1.0: 環境変数の読み込み
• mysql-connector-python==8.2.0: MySQL データベースコネクタ
• uvicorn==0.24.0: ASGI サーバー

⚙️ 設定

1. 環境変数の設定

.env.example ファイルを .env にコピーし、データベースの接続情報を設定します。

cp .env.example .env

.env ファイルを編集します。

# データベース設定
DB_HOST=localhost
DB_PORT=3306
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database

# オプション：サーバー設定
MCP_HOST=127.0.0.1
MCP_PORT=8000

2. データベースの初期化

提供されている dataset.sql ファイルを使用して、サンプルデータを初期化します。

mysql -u your_username -p your_database < dataset.sql

このファイルには contracts テーブルのサンプルデータが含まれており、契約情報が格納されています。

🚀 サービスの起動

python mcp_server.py

サービスが起動すると、以下のように表示されます。

Authorization=Bearer ...
🚀 MCP データクエリサーバーを起動します...
📍 アドレス: http://127.0.0.1:8000
📋 利用可能なツール:
   - health_check: ヘルスチェック
   - get_user_permissions: ユーザーの権限を取得
   - get_database_tables: データベースのテーブルリストを取得
   - get_table_structure: テーブル構造を取得
   - execute_sql_query: SQL クエリを実行
   - generate_sql_from_question: 自然言語から SQL を生成
   - analyze_query_result: クエリ結果の分析

MCP クライアントの設定

🔧 API ツール

1. ヘルスチェック

• ツール名: health_check
• 説明: サービスとデータベースの接続状態を確認します。
• 権限: 特別な権限は不要です。

2. ユーザー権限の取得

• ツール名: get_user_permissions
• 説明: 現在のユーザーの権限情報を取得します。
• 権限: 有効なアクセストークンが必要です。

3. データベースのテーブルリストの取得

• ツール名: get_database_tables
• 説明: データベース内のすべてのテーブルのリストを取得します。
• 権限: data:read_tables 権限が必要です。

4. テーブル構造の取得

• ツール名: get_table_structure
• パラメータ:
  • table_name (string): テーブル名
• 説明: 指定されたテーブルの構造情報、行数、サンプルデータを取得します。
• 権限: data:read_tables 権限が必要です。

5. SQL クエリの実行

• ツール名: execute_sql_query
• パラメータ:
  • sql_query (string): SQL クエリ文
  • limit (int, オプション): 返される結果の最大行数、デフォルトは 100
• 説明: 安全に SQL クエリを実行します。
• 権限: data:read_table_data 権限が必要です。
• セキュリティ制限: DROP、DELETE、UPDATE、INSERT などの変更操作は禁止されています。

🔐 セキュリティ機能

権限システム

• RSA 鍵ペアに基づく JWT Token 認証
• 細かい粒度の権限制御：
  • data:read_tables: テーブル構造を読み取る権限
  • data:read_table_data: テーブルデータを読み取る権限

セキュリティチェック

• SQL インジェクション防止: 危険な SQL 操作を禁止します。
• クエリ制限: 自動的に LIMIT 制限を追加し、大量のデータクエリを防止します。
• 機密データ保護: 機密キーワードを含むクエリに対して、追加の権限チェックを行います。

📁 プロジェクト構造

text-to-sql-mcp/
├── mcp_server.py          # メインサーバーファイル
├── database.py            # データベース管理モジュール
├── auth_token.py          # 認証トークン生成モジュール
├── requirements.txt       # プロジェクトの依存関係
├── .env.example          # 環境変数のサンプル
├── dataset.sql           # サンプルデータベース構造とデータ
└── README.md             # プロジェクトドキュメント

🔍 核心モジュールの説明

mcp_server.py メインサーバーファイルで、以下を含みます。

• MCP サーバーの初期化
• すべての API ツールの定義
• 権限検証ロジック
• セキュリティチェックメカニズム

database.py データベース管理モジュールで、以下を提供します。

• MySQL データベースの接続管理
• SQL クエリの実行
• テーブル構造情報の取得
• データ型の変換

auth_token.py 認証モジュールで、以下を担当します。

• RSA 鍵ペアの生成
• JWT アクセストークンの作成
• 認証プロバイダの設定

🚨 注意事項

1. データベースのセキュリティ: データベースユーザーの権限を最小限に抑え、必要なクエリ権限のみを付与してください。
2. ネットワークセキュリティ: 本番環境では HTTPS とファイアウォールを使用して保護することをおすすめします。
3. トークン管理: アクセストークンを定期的に更新し、同じトークンを長期間使用しないでください。
4. クエリ監視: クエリのパフォーマンスを監視し、複雑なクエリがデータベースのパフォーマンスに影響を与えないようにしてください。

🤝 コントリビューション

このプロジェクトを改善するために、Issue や Pull Request の投稿を歓迎します。

私の作品

n8n ワークフロー自動化テンプレートサイトで、多数の直接使用可能な自動化フローが収集されています。https://n8ntemplates.dev