Purpose: Act as an MCP server to execute SQL queries and stream results to CSV or Parquet files via ConnectorX, avoiding direct transmission of large volumes of data in MCP communication.
Main capabilities: Supports two output formats: CSV (UTF-8, always writes a header) and Parquet (PyArrow default settings; inconsistent schemas between batches will cause an error). Results are read in chunks as Arrow RecordBatch, with a default batch_size of 100000 rows. For empty results, CSV produces an empty file, and Parquet writes an empty table. On execution failure, returns Error: <message> and deletes the partially written output file. Optional CSV per-line token counting uses tiktoken(o200k_base), and an alert threshold can be set.
Usage: Exposes a single run_sql as an MCP tool. Use --conn <connection_token> (required) to specify the ConnectorX connection token, supporting SQLite, PostgreSQL, BigQuery, etc.; --csv-token-threshold <int> (default 0), when greater than 0, enables CSV per-line token counting and serves as the alert threshold. It can be started in MCP-capable clients (such as Cursor) via .cursor/mcp.json in the project root directory. For the connection token format and the complete list of supported databases, see the official ConnectorX documentation.
Return value: On success, returns the string OK; when CSV token counting is enabled, may return OK N tokens, with a hint attached when N reaches the threshold; for empty results with counting enabled, returns OK 0 tokens.
Limitations: Only CSV or Parquet output is supported; Parquet schemas must be consistent between batches; information not provided is not yet available, for example specific pricing, deployment methods, and complete parameter details for each database connection require consulting the ConnectorX documentation.
