# andyWang1688/sql-query-mcp [Health: Active]

**Category:** 🗄️ Databases  
**Repository:** https://github.com/andyWang1688/sql-query-mcp  
**GitHub Stars:** 6  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/andywang1688-sql-query-mcp

## Description
A general-purpose MCP server that lets AI work with multiple databases within clear boundaries. Supports PostgreSQL and MySQL today with schema discovery, sampling, read-only queries, and query-plan inspection.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `pipx` (confidence: high):

```json
"mcpServers": {
  "sql-query-mcp": {
    "command": "pipx",
    "args": ["run","sql-query-mcp","sql-query-mcp"],
    "env": {
      "SQL_QUERY_MCP_CONFIG": ""
    }
  }
}
```

**Requires environment variables:** `SQL_QUERY_MCP_CONFIG` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/andywang1688-sql-query-mcp/readme_