Sql Query MCP

What the andyWang1688/sql-query-mcp MCP server does

andyWang1688/sql-query-mcp MCP server gives an MCP client a controlled interface to configured PostgreSQL, MySQL, and Hive connections. It supports database structure discovery, table and column inspection, small data samples, read-only SQL, asynchronous query handling, and query-plan inspection. PostgreSQL uses schemas as namespaces; MySQL and Hive use databases.

The server also provides limited file exchange. PostgreSQL and MySQL query results can be written to local CSV or XLSX files. CSV/XLSX files can be imported into existing tables when their headers match table columns exactly. The import operation is the only database write path described by the project.

How it works

Connections are declared in a JSON configuration file. Each connection identifies its engine, connection ID, namespace defaults, and the name of an environment variable containing the real DSN. This keeps credentials out of the configuration file. The MCP client supplies SQL_QUERY_MCP_CONFIG and the DSN variables in its environment when starting the process.

SQL passes through sqlglot validation before execution. Query tools accept only SELECT statements and WITH ... SELECT statements; comments and multiple statements are rejected. Use run_select for short, bounded work. For longer read-only operations, start_query begins execution, get_query retrieves status and paginated results, and cancel_query stops a running query. Calls are recorded in an audit log.

Setup and configuration

The project documents two PyPI-based startup modes. Install the command with pipx install sql-query-mcp, then start sql-query-mcp, or let an MCP client launch it with pipx run --spec sql-query-mcp sql-query-mcp. Set SQL_QUERY_MCP_CONFIG to the connections file, such as a file under ~/.config/sql-query-mcp, rather than relying on the source-checkout default path.

Configuration settings can define default and maximum result limits plus an audit-log path. Each connection needs an explicit engine and a dsn_env entry. PostgreSQL connections may specify default_schema; MySQL and Hive connections may specify default_database. The README includes examples for PostgreSQL, MySQL, and Hive DSNs, but the actual credential-bearing values must be supplied by the operator.

Tools and capabilities

The documented tool set includes:

• Listing configured connections, schemas, databases, tables, and views.
• Describing table columns, keys, and indexes.
• Running bounded read-only queries and retrieving table samples.
• Starting, paging through, and cancelling asynchronous read-only queries.
• Inspecting plans with EXPLAIN; Hive also supports EXPLAIN ANALYZE through the plan tool.
• Exporting PostgreSQL and MySQL results to local CSV/XLSX files.
• Importing local CSV/XLSX data into existing tables.

Limitations and notes

SQLite, SQL Server, and ClickHouse are listed as candidates and are not supported yet. Hive does not support query-result export. Hive file imports are intended for small files and reject inputs with more than 1,000 data rows; row-by-row insertion can also exceed an MCP client timeout. Large exports may face the same timeout issue because export is synchronous, even though rows are processed in batches.

Files are written to or read from the machine running the MCP server, not necessarily the machine displaying the AI client. Imports do not accept raw SQL and only insert file fields whose headers exactly match existing columns. The andyWang1688/sql-query-mcp MCP server therefore fits controlled database inspection and bounded data workflows better than unrestricted administration or bulk-loading operations.