Run SQL Connectorx

1# run-sql-connectorx
2 
3An MCP server that executes SQL via **ConnectorX** and streams the result to **CSV** or **Parquet** in 
4PyArrow `RecordBatch` chunks.
5 
6* **Output formats**: `csv` or `parquet`
7* **CSV**: UTF-8, header row is always written
8* **Parquet**: PyArrow defaults; schema mismatch across batches raises an error
9* **Return value**: the string `"OK"` on success, or `"Error: <message>"` on failure
10* On failure the partially written output file is deleted
11* **CSV token counting (optional)**: per-line token counting via `tiktoken` (`o200k_base`) with a warning threshold
12 
13## Why this library?
14 
15- **Efficient streaming**: handles large results in Arrow `RecordBatch` chunks
16- **Token-efficient for MCP**: exchanges data via files instead of inline payloads
17- **Cross-database via ConnectorX**: one tool works across many backends
18- **Robust I/O**: CSV header handling, Parquet schema validation, safe cleanup on errors
19 
20## Supported data sources (ConnectorX)
21 
22ConnectorX supports many databases. Common examples include:
23 
24- **PostgreSQL**
25- **MySQL / MariaDB**
26- **SQLite**
27- **Microsoft SQL Server**
28- **Amazon Redshift**
29- **Google BigQuery**
30 
31For the complete and up-to-date list of supported databases and connection-token (`conn`) formats, see the official docs:
32 
33- ConnectorX repository: <https://github.com/sfu-db/connector-x/>
34- Database connection tokens: <https://github.com/sfu-db/connector-x/tree/main/docs/databases>
35 
36## Getting Started
37 
38```bash
39uvx run-sql-connectorx \
40  --conn "<connection_token>" \
41  --csv-token-threshold 500000
42```
43 
44<connection_token> is the **connection token** (*conn*) used by ConnectorX—SQLite, PostgreSQL, BigQuery, and more.
45 
46## CLI options
47 
48- `--conn <connection_token>` (required): ConnectorX connection token (`conn`)
49- `--csv-token-threshold <int>` (default `0`): when `> 0`, enable CSV per-line token counting using `tiktoken(o200k_base)`; the value is a warning threshold
50 
51### Further reading
52 
53* ConnectorX repository: <https://github.com/sfu-db/connector-x/>
54* Connection-token formats for each database: <https://github.com/sfu-db/connector-x/tree/main/docs/databases>
55 
56### Running from *mcp.json*
57 
58To launch the server from an MCP-aware client such as **Cursor**, add the following snippet to
59`.cursor/mcp.json` at the project root:
60 
61```json
62{
63  "mcpServers": {
64    "run-sql-connectorx": {
65      "command": "uvx",
66      "args": [
67        "--from", "git+https://github.com/gigamori/mcp-run-sql-connectorx",
68        "run-sql-connectorx",
69        "--conn", "<connection_token>"
70      ]
71    }
72  }
73}
74```
75 
76## Behaviour and Limits
77 
78* **Streaming**: Results are streamed from ConnectorX in RecordBatch chunks; the default
79  `batch_size` is `100 000` rows.
80* **Empty result**:
81  * CSV – an empty file is created
82  * Parquet – an empty table is written
83* **Error handling**: the output file is removed on any exception.
84* **CSV token counting (when `--csv-token-threshold > 0`)**:
85  - Counted text: exactly what `csv.writer` writes (including header row when present, delimiters, quotes, and newlines), UTF-8
86  - Streaming approach: tokenized with `tiktoken(o200k_base)` per written CSV line
87 
88## Call output
89 
90The tool returns a single text message.
91 
92- On success:
93  - Parquet: `OK`
94  - CSV:
95    - If `--csv-token-threshold = 0`: `OK`
96    - If `--csv-token-threshold > 0`: `OK N tokens` (or `OK N tokens. Too many tokens may impair processing. Handle appropriately` when `N >= threshold`)
97    - Empty result with counting enabled: `OK 0 tokens`
98- On failure: `Error: <message>` (any partial output file is deleted)
99 
100## MCP Tool Specification
101 
102The server exposes a single MCP tool **`run_sql`**.
103 
104| Argument        | Type   | Required | Description                    |
105|-----------------|--------|----------|--------------------------------|
106| `sql_file`      | string | yes      | Path to a file that contains the SQL text to execute |
107| `output_path`   | string | yes      | Destination file for the query result |
108| `output_format` | enum   | yes      | One of `"csv"` or `"parquet"`   |
109| `batch_size`    | int    | no       | RecordBatch size (default `100000`) |
110 
111### Example Call
112 
113```json
114{
115  "tool": "run_sql",
116  "arguments": {
117    "sql_file": "sql/queries/sales.sql",
118    "output_path": "output/sales.parquet",
119    "output_format": "parquet",
120    "batch_size": 200000
121  }
122}
123```
124 
125---
126 
127## License
128 
129Distributed under the MIT License. See `LICENSE` for details.
130