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 支持跨数据库操作：一个工具即可适配多种后端
• 可靠的 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 编码
  • 流式处理方式：使用 tiktoken(o200k_base) 对写入的每一行 CSV 进行令牌化

调用输出

该工具返回一条文本消息。

• 成功时：
  • 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	字符串	是	包含要执行的 SQL 文本的文件路径
output_path	字符串	是	查询结果的目标文件
output_format	枚举	是	"csv" 或 "parquet" 之一
batch_size	整数	否	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。