run-sql-connectorx
About
Execute SQL (PostgreSQL, MariaDB, BigQuery, MS SQL Server, RedShift, etc.) via ConnectorX and stream results to CSV/Parquet. MCP tool: run_sql.
Details
- Author
- gigamori
- Downloads
- 266
- Categories
- Other, Database
Jump to
- Efficient streaming via Arrow RecordBatch chunks
- Token-efficient file-based data exchange for MCP
- Cross-database support through ConnectorX
- Robust I/O: CSV headers, Parquet validation, error cleanup
- Output formats: CSV (UTF‑8) and Parquet (PyArrow defaults)
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
run-sql-connectorxCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install via uvx and invoke with the required --conn <connection_token> option. Optionally set --csv-token-threshold <int> to enable per‑line CSV token counting. The server returns the string "OK" on success or "Error: <message>" on failure.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"run-sql-connectorx": {
"run-sql-connectorx": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/gigamori/mcp-run-sql-connectorx",
"run-sql-connectorx",
"--conn",
"<connection_token>",
"--csv-token-threshold",
"500000"
]
}
}
}
}McpServers
{
"run-sql-connectorx": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/gigamori/mcp-run-sql-connectorx",
"run-sql-connectorx",
"--conn",
"<connection_token>",
"--csv-token-threshold",
"500000"
]
}
} 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: <message>" 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: <https://github.com/sfu-db/connector-x/>
- Database connection tokens: <https://github.com/sfu-db/connector-x/tree/main/docs/databases>
Getting Started
``
bash
uvx run-sql-connectorx \
--conn "<connection_token>" \
--csv-token-threshold 500000
`
<connection_token> is the connection token (conn) used by ConnectorX—SQLite, PostgreSQL, BigQuery, and more.
CLI options
- (required): ConnectorX connection token (conn)
- --csv-token-threshold <int> (default 0): when > 0, enable CSV per-line token counting using tiktoken(o200k_base)`; the value is a warning thresholdFurther reading
ConnectorX repository: <https://github.com/sfu-db/connector-x/>
Connection-token formats for each database: <https://github.com/sfu-db/connector-x/tree/main/docs/databases>
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
