Run Sql Connectorx

run-sql-connectorx

ConnectorX 経由で SQL を実行し、結果を PyArrow の RecordBatch チャンクで CSV または Parquet にストリーミングする MCP サーバーです。

• 出力形式：csv または parquet
• CSV：UTF-8、ヘッダー行は常に書き込まれます
• Parquet：PyArrow のデフォルト設定を使用します。バッチ間でスキーマが一致しない場合はエラーになります
• 戻り値：成功時は文字列 "OK"、失敗時は "Error: <message>"
• 失敗時は、途中まで書き込まれた出力ファイルが削除されます
• CSV のトークン数カウント（任意）：警告しきい値を設定して、tiktoken（o200k_base）で行ごとにトークン数をカウントします

このライブラリを使う理由

• 効率的なストリーミング：Arrow の RecordBatch チャンクで大規模な結果を処理します
• MCP でのトークン効率：インラインペイロードではなく、ファイル経由でデータをやり取りします
• ConnectorX によるクロスデータベース対応：1 つのツールで多くのバックエンドに対応します
• 堅牢な I/O：CSV のヘッダー処理、Parquet のスキーマ検証、エラー発生時の安全なクリーンアップに対応します

対応データソース（ConnectorX）

ConnectorX は多くのデータベースに対応しています。一般的な例は次のとおりです。

• PostgreSQL
• MySQL / MariaDB
• SQLite
• Microsoft SQL Server
• Amazon Redshift
• Google BigQuery

対応データベースと接続トークン（conn）形式の完全かつ最新の一覧については、公式ドキュメントをご覧ください。

• ConnectorX リポジトリ：https://github.com/sfu-db/connector-x/
• データベース接続トークン：https://github.com/sfu-db/connector-x/tree/main/docs/databases

はじめに

uvx run-sql-connectorx \
  --conn "<connection_token>" \
  --csv-token-threshold 500000

<connection_token> は、ConnectorX が使用する接続トークン（conn）です。SQLite、PostgreSQL、BigQuery などに対応しています。

CLI オプション

• --conn <connection_token>（必須）：ConnectorX の接続トークン（conn）
• --csv-token-threshold <int>（デフォルトは 0）：> 0 の場合、tiktoken(o200k_base) を使用して CSV のトークン数を行ごとにカウントします。この値は警告しきい値です

詳細情報

• ConnectorX リポジトリ：https://github.com/sfu-db/connector-x/
• 各データベースの接続トークン形式：https://github.com/sfu-db/connector-x/tree/main/docs/databases

mcp.json から実行する

Cursor などの MCP 対応クライアントからサーバーを起動するには、プロジェクトルートにある .cursor/mcp.json に次のスニペットを追加します。

{
  "mcpServers": {
    "run-sql-connectorx": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/gigamori/mcp-run-sql-connectorx",
        "run-sql-connectorx",
        "--conn", "<connection_token>"
      ]
    }
  }
}

動作と制限

• ストリーミング：ConnectorX から結果を RecordBatch チャンクでストリーミングします。デフォルトの batch_size は 100 000 行です。
• 空の結果：
  • CSV – 空のファイルが作成されます
  • Parquet – 空のテーブルが書き込まれます
• エラー処理：例外が発生すると、出力ファイルが削除されます。
• CSV のトークン数カウント（--csv-token-threshold > 0 の場合）：
  • カウント対象のテキスト：csv.writer が書き込む内容そのもの（存在する場合はヘッダー行、区切り文字、引用符、改行を含む）、UTF-8
  • ストリーミング方式：書き込まれた CSV の各行を tiktoken(o200k_base) でトークン化します

呼び出しの出力

このツールは単一のテキストメッセージを返します。

• 成功時：
  • Parquet：OK
  • CSV：
    • --csv-token-threshold = 0 の場合：OK
    • --csv-token-threshold > 0 の場合：OK N tokens（または N >= threshold の場合は OK N tokens. Too many tokens may impair processing. Handle appropriately）
    • カウント有効時に結果が空の場合：OK 0 tokens
• 失敗時：Error: <message>（途中まで出力されたファイルは削除されます）

MCP ツール仕様

このサーバーは単一の MCP ツール run_sql を公開します。

引数	型	必須	説明
sql_file	string	はい	実行する SQL テキストを含むファイルのパス
output_path	string	はい	クエリ結果の出力先ファイル
output_format	enum	はい	"csv" または "parquet" のいずれか
batch_size	int	いいえ	RecordBatch のサイズ（デフォルトは 100000）

呼び出し例

{
  "tool": "run_sql",
  "arguments": {
    "sql_file": "sql/queries/sales.sql",
    "output_path": "output/sales.parquet",
    "output_format": "parquet",
    "batch_size": 200000
  }
}

---

ライセンス

MIT License の下で配布されています。詳細は LICENSE をご覧ください。