text2sql

text2sql-mcp

text2sql-framework 用の MCP サーバーです。Claude Desktop、Cursor、Goose、またはその他の MCP 互換アシスタントに接続して、SQL データベースに自然言語で質問できます。

エージェントがスキーマを調べ、SQL を作成し、実際のデータベースに対して実行して、エラーが発生した場合は自動で修正します。RAG レイヤーも、スキーマの説明も、事前計算済みの埋め込みも必要ありません。

インストール

標準では、text2sql-mcp は SQLite + Anthropic に対応しています。

pip install text2sql-mcp
# or
uvx text2sql-mcp

その他のデータベースや LLM プロバイダーを使用する場合は、対応する追加パッケージを指定してインストールし、適切なドライバーをインストールしてください。

使用するもの…	インストールコマンド
SQLite（デフォルト）	uvx text2sql-mcp
Postgres	uvx 'text2sql-mcp[postgres]'
MySQL	uvx 'text2sql-mcp[mysql]'
Snowflake	uvx 'text2sql-mcp[snowflake]'
BigQuery	uvx 'text2sql-mcp[bigquery]'
OpenAI モデル	openai を追加します。例：uvx 'text2sql-mcp[postgres,openai]'

設定

MCP クライアントの設定で環境変数を指定します。

変数	必須	説明
TEXT2SQL_DATABASE_URL	はい	SQLAlchemy の URL。例：sqlite:///mydb.db、postgresql://user:pass@host/db
ANTHROPIC_API_KEY または OPENAI_API_KEY	はい	LLM プロバイダーのキー
TEXT2SQL_MODEL	いいえ	LangChain のモデル ID（デフォルト：anthropic:claude-sonnet-4-6）
TEXT2SQL_INSTRUCTIONS	いいえ	ビジネスルールやヒント。例：「売上は返金額を差し引いた金額です。」
TEXT2SQL_EXAMPLES	いいえ	エージェントの lookup_example ツール用の scenarios.md ファイルのパス

Claude Desktop / Cursor / 汎用 MCP

{
  "mcpServers": {
    "text2sql": {
      "command": "uvx",
      "args": ["text2sql-mcp"],
      "env": {
        "TEXT2SQL_DATABASE_URL": "sqlite:///mydb.db",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Goose CLI

goose configure
# Add Extension → Command-line Extension
# Name: text2sql
# Command: uvx text2sql-mcp
# Env: TEXT2SQL_DATABASE_URL, ANTHROPIC_API_KEY

ツール

• query(question, max_rows=100) — データベースに自然言語で質問します。{sql, data, error, row_count, tool_calls_made} を返します。

仕組み

内部では、text2sql-framework を薄くラップしています。このフレームワークは LangChain Deep Agents を使用し、単一の execute_sql ツールに対して反復的にツールを呼び出します。ベンチマーク（80 テーブルを対象にした Spider のゼロショット評価で 19/20）とアーキテクチャの詳細については、フレームワークの README をご覧ください。

ライセンス

MIT