A general-purpose MCP server that lets AI work with multiple databases
sql-query-mcp
A general-purpose MCP server that lets AI work with multiple databases within clear boundaries.
Current database support
| Database | Status | Current availability |
|---|---|---|
| PostgreSQL | Supported | Available today |
| MySQL | Supported | Available today |
| SQLite | Candidate | Not supported yet |
| SQL Server | Candidate | Not supported yet |
| ClickHouse | Candidate | Not supported yet |
Product value
sql-query-mcp helps AI clients discover schema, sample data, and analyze
read-only queries through one controlled MCP interface.
It keeps connection handling, namespace rules, SQL validation, and audit logging on the server side, so you can expose useful database context to AI without exposing raw connection strings or flattening engine-specific concepts.
What AI can do with it
The current tool set focuses on database discovery and controlled query workflows. You can use it to help an AI assistant understand structure before it generates or refines SQL.
MySQL supports explain_query, but not explain_query(..., analyze=True) in
the current implementation.
| Tool | PostgreSQL | MySQL | Purpose |
|---|---|---|---|
list_connections() |
Yes | Yes | List configured connections |
list_schemas(connection_id) |
Yes | No | List visible PostgreSQL schemas |
list_databases(connection_id) |
No | Yes | List visible MySQL databases |
list_tables(connection_id, schema?, database?) |
Yes | Yes | List tables and views |
describe_table(connection_id, table_name, schema?, database?) |
Yes | Yes | Inspect columns, keys, and indexes |
run_select(connection_id, sql, limit?) |
Yes | Yes | Run read-only queries |
explain_query(connection_id, sql, analyze?) |
Yes | Yes | Inspect query plans |
get_table_sample(connection_id, table_name, schema?, database?, limit?) |
Yes | Yes | Fetch small table samples |
These tools are useful for tasks such as listing namespaces, inspecting table
definitions, reviewing indexes, sampling records, and analyzing read-only
queries with EXPLAIN. For full request and response details, see
docs/api-reference.md (Chinese).
How boundaries are constrained
The product boundary is intentionally narrow today. Only PostgreSQL and MySQL are available today, and the current tool set is fully read-only.
The service keeps those boundaries explicit in a few ways.
- Connections declare
engineexplicitly, so the server never guesses fromconnection_id. - PostgreSQL uses
schema, and MySQL usesdatabase, without collapsing both into one vague namespace field. - Real DSNs stay in environment variables, while config files store only the environment variable names.
- Query execution passes through
sqlglotvalidation before reaching the database. - The server accepts only
SELECTandWITH ... SELECT, rejects comments and multi-statement input, and records audit logs for each call.
For MySQL, explain_query(..., analyze=True) is not available in the current
implementation.
Quick start
sql-query-mcp supports two official PyPI-based setup modes. Both are intended
for real usage, not just local testing.
- Choose how you want your MCP client to start the server.
Use installed command mode if you want a simple local command after one install.
pipx install sql-query-mcp
Use managed launch mode if you want the package source declared directly in your MCP client config.
pipx run --spec sql-query-mcp sql-query-mcp
Pin a version with pipx install 'sql-query-mcp==X.Y.Z' or
pipx run --spec 'sql-query-mcp==X.Y.Z' sql-query-mcp. Upgrade installed
command mode with pipx upgrade sql-query-mcp.
- Create a config file.
The server configuration should live outside the repository so the same file works with either startup mode.
mkdir -p ~/.config/sql-query-mcp
Then save the example JSON later in this section as
~/.config/sql-query-mcp/connections.json.
- Register the server in your MCP client.
- Codex:
docs/codex-setup.md(Chinese) - OpenCode:
docs/opencode-setup.md(Chinese)
Installed command mode means your client runs sql-query-mcp directly.
Managed launch mode means your client starts the server through pipx run.
In both modes, put SQL_QUERY_MCP_CONFIG and your real database DSNs in the
MCP client's environment block instead of exporting them in your shell.
The console entry point is sql-query-mcp, which maps to
sql_query_mcp.app:main.
The PyPI install name is sql-query-mcp, and the Python package import path is
sql_query_mcp.
For pipx install and pipx run, set SQL_QUERY_MCP_CONFIG explicitly to
your config file path. The default config/connections.json path is mainly for
source checkouts and local development.
The example config looks li
Tools (8)
list_connectionsList configured database connectionslist_schemasList visible PostgreSQL schemaslist_databasesList visible MySQL databaseslist_tablesList tables and viewsdescribe_tableInspect columns, keys, and indexes of a tablerun_selectRun read-only SQL queriesexplain_queryInspect query execution plansget_table_sampleFetch small table samplesEnvironment Variables
SQL_QUERY_MCP_CONFIGrequiredPath to the JSON configuration file containing database connectionsConfiguration
{"mcpServers": {"sql-query-mcp": {"command": "sql-query-mcp", "env": {"SQL_QUERY_MCP_CONFIG": "/path/to/connections.json", "DB_DSN_1": "postgresql://user:pass@host:5432/db"}}}}