MCP Run Sql Connectorx

What gigamori/mcp-run-sql-connectorx MCP server does

The gigamori/mcp-run-sql-connectorx MCP server exposes one MCP tool, run_sql, for executing SQL stored in a file. The tool writes the query result to a caller-selected output path in either CSV or Parquet format. It returns a short text status rather than embedding the result data in the MCP response.

The server delegates database access to ConnectorX. The README lists PostgreSQL, MySQL and MariaDB, SQLite, Microsoft SQL Server, Amazon Redshift, and Google BigQuery as common supported sources. The exact connection-token syntax depends on ConnectorX and the selected database.

CSV output is UTF-8 encoded and always includes a header row when the result has columns. Parquet output uses PyArrow defaults. If batches do not share a compatible schema, Parquet writing fails rather than producing an inconsistent file.

How it works

A client supplies four main values to run_sql:

• sql_file: path to the file containing the SQL statement
• output_path: destination for the generated file
• output_format: either csv or parquet
• batch_size: optional RecordBatch size, defaulting to 100,000 rows

Results are streamed from ConnectorX in Arrow RecordBatch chunks. This allows output to be written incrementally instead of collecting the complete result in the MCP message. Empty queries still produce an output: CSV creates an empty file, while Parquet writes an empty table.

Successful calls return OK. CSV calls can optionally report a token count, while failures return an error message and remove any partially written output file.

Setup and configuration

The gigamori/mcp-run-sql-connectorx MCP server is launched with uvx and requires a ConnectorX conn connection token. The README shows the project being launched from its Git repository with the run-sql-connectorx command and a required --conn option. Connection-token formats are maintained in the ConnectorX documentation rather than defined by this MCP project.

The optional --csv-token-threshold CLI option enables per-line CSV token counting with tiktoken using the o200k_base encoding. Its default is 0, which disables counting. When enabled, the value acts as a warning threshold. The counted text is the exact CSV output, including headers, delimiters, quotes, and line endings.

The README includes a Cursor configuration example using .cursor/mcp.json. The example starts the server with uvx, references the GitHub repository, and passes the connection token as an argument.

Tools and capabilities

The only exposed tool is run_sql. It supports:

• SQL loaded from a file rather than an inline tool argument
• CSV and Parquet destinations
• Configurable Arrow batch sizes
• ConnectorX database backends
• Incremental output for large query results
• Optional CSV token accounting
• Cleanup of partial files after exceptions

When CSV counting is active, a successful response reports the number of tokens. If the count reaches the configured threshold, the response also warns that the result may impair processing. Parquet calls return OK without CSV token counting.

Limitations and notes

The gigamori/mcp-run-sql-connectorx MCP server does not document a separate database abstraction or connection-management layer; database support and connection-token details come from ConnectorX. The SQL must be available in a file accessible to the server, and the caller must provide an output path.

Parquet schema differences between streamed batches cause an error. Any exception deletes the incomplete output. Credentials and endpoint details are part of the ConnectorX connection token, so deployment should protect the command configuration and related files. The README identifies the project as MIT licensed.