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 engine explicitly, so the server never guesses from connection_id.
• PostgreSQL uses schema, and MySQL uses database, 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 sqlglot validation before reaching the database.
• The server accepts only SELECT and WITH ... 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

If you want to get the server running first and explore the rest later, follow these steps.

1. Create a virtual environment and install the project.

python3.10 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install sql-query-mcp

Install a specific release with pip install sql-query-mcp==X.Y.Z if you want to pin a version. Published release artifacts are also attached to each GitHub Release.

2. Copy the example connection config.

cp config/connections.example.json config/connections.json

3. Export your database DSNs as environment variables.

These example names match the copied config/connections.example.json file.

export PG_CONN_CRM_PROD_MUQIAO_RO='postgresql://user:password@host:5432/dbname'
export MYSQL_CONN_CRM_PROD_MUQIAO_RO='mysql://user:password@host:3306/crm'
export SQL_QUERY_MCP_CONFIG='/absolute/path/to/sql-query-mcp/config/connections.json'

4. Register the server in your MCP client.

• Codex: docs/codex-setup.md (Chinese)
• OpenCode: docs/opencode-setup.md (Chinese)

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.

The default config path is config/connections.json. If you need a different location, set SQL_QUERY_MCP_CONFIG.

The example config looks like this.

{
  "settings": {
    "default_limit": 200,
    "max_limit": 1000,
    "audit_log_path": "logs/audit.jsonl"
  },
  "connections": [
    {
      "connection_id": "crm_prod_muqiao_ro",
      "engine": "postgres",
      "label": "CRM PostgreSQL production / Muqiao / read-only",
      "env": "prod",
      "tenant": "muqiao",
      "role": "ro",
      "dsn_env": "PG_CONN_CRM_PROD_MUQIAO_RO",
      "enabled": true,
      "default_schema": "public"
    },
    {
      "connection_id": "crm_mysql_prod_muqiao_ro",
      "engine": "mysql",
      "label": "CRM MySQL production / Muqiao / read-only",
      "env": "prod",
      "tenant": "muqiao",
      "role": "ro",
      "dsn_env": "MYSQL_CONN_CRM_PROD_MUQIAO_RO",
      "enabled": true,
      "default_database": "crm"
    }
  ]
}

Documentation

If you want implementation details, setup guidance, or internal structure, use these docs as your starting points.

• docs/project-overview.md: project goals, concepts, and code structure (Chinese)
• docs/api-reference.md: MCP tool reference (Chinese)
• docs/codex-setup.md: Codex setup steps (Chinese)
• docs/opencode-setup.md: OpenCode setup steps (Chinese)
• docs/release-process.md: PyPI and GitHub Release workflow (Chinese)
• docs/git-workflow.md: repository collaboration workflow (Chinese)

Development

If you want to modify or verify the project locally, use this shortest path. Editable install remains the development path, and the local environment still requires Python 3.10+.

python3.10 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e .
PYTHONPATH=. python3 -m unittest discover -s tests

The main entry point is sql_query_mcp/app.py. Core modules include:

• sql_query_mcp/config.py: config loading and validation
• sql_query_mcp/validator.py: read-only SQL validation
• sql_query_mcp/introspection.py: metadata inspection
• sql_query_mcp/executor.py: query execution and limits
• sql_query_mcp/adapters/: PostgreSQL and MySQL adapters

Contributing

If you want to contribute or review the repository workflow, start with these pages.

• CONTRIBUTING.md
• docs/roadmap.md
• docs/git-workflow.md (Chinese)

Run PYTHONPATH=. python3 -m unittest discover -s tests before you submit changes.

License

This project is released under the MIT License. See LICENSE.