gigamori/mcp-run-sql-connectorx

An MCP server that executes SQL via **ConnectorX** and streams the result to **CSV** or **Parquet** in
PyArrow RecordBatch chunks.
* **Output formats**: csv or parquet
* **CSV**: UTF-8, header row is always written
* **Parquet**: PyArrow defaults; schema mismatch across batches raises an error
* **Return value**: the string "OK" on success, or "Error: " on failure
* On failure the partially written output file is deleted
* **CSV token counting (optional)**: per-line token counting via tiktoken (o200k_base) with a warning threshold
Why this library?
- **Efficient streaming**: handles large results in Arrow RecordBatch chunks
- **Token-efficient for MCP**: exchanges data via files instead of inline payloads
- **Cross-database via ConnectorX**: one tool works across many backends
- **Robust I/O**: CSV header handling, Parquet schema validation, safe cleanup on errors
Supported data sources (ConnectorX)
ConnectorX supports many databases. Common examples include:
- **PostgreSQL**
- **MySQL / MariaDB**
- **SQLite**
- **Microsoft SQL Server**
- **Amazon Redshift**
- **Google BigQuery**
For the complete and up-to-date list of supported databases and connection-token (conn) formats, see the official docs:
- ConnectorX repository:
- Database connection tokens:
Getting Started
is the **connection token** (*conn*) used by ConnectorX—SQLite, PostgreSQL, BigQuery, and more.
CLI options
- --conn (required): ConnectorX connection token (conn)
- --csv-token-threshold (default 0): when > 0, enable CSV per-line token counting using tiktoken(o200k_base); the value is a warning threshold
Further reading
* ConnectorX repository:
* Connection-token formats for each database:
Running from *mcp.json*
To launch the server from an MCP-aware client such as **Cursor**, add the following snippet to
.cursor/mcp.json at the project root:
Behaviour and Limits
* **Streaming**: Results are streamed from ConnectorX in RecordBatch chunks; the default
batch_size is 100 000 rows.
* **Empty result**:
* CSV – an empty file is created
* Parquet – an empty table is written
* **Error handling**: the output file is removed on any exception.
* **CSV token counting (when --csv-token-threshold > 0)**:
- Counted text: exactly what csv.writer writes (including header row when present, delimiters, quotes, and newlines), UTF-8
- Streaming approach: tokenized with tiktoken(o200k_base) per written CSV line
Call output
The tool returns a single text message.
- On success:
- Parquet: OK
- CSV:
- If --csv-token-threshold = 0: OK
- If --csv-token-threshold > 0: OK N tokens (or OK N tokens. Too many tokens may impair processing. Handle appropriately when N >= threshold)