sql-query-mcp

sql-query-mcp

中文版

A general-purpose MCP server that lets AI work with multiple databases withinclear boundaries.

Current database support

Product value

sql-query-mcp helps AI clients discover schema, sample data, and analyzeread-only queries through one controlled MCP interface.

It keeps connection handling, namespace rules, SQL validation, and auditlogging on the server side, so you can expose useful database context to AIwithout 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 queryworkflows. You can use it to help an AI assistant understand structure beforeit generates or refines SQL.

MySQL supports explain_query, but not explain_query(..., analyze=True) inthe current implementation.

These tools are useful for tasks such as listing namespaces, inspecting tabledefinitions, reviewing indexes, sampling records, and analyzing read-onlyqueries with EXPLAIN. For full request and response details, seedocs/api-reference.md (Chinese).

How boundaries are constrained

The product boundary is intentionally narrow today. Only PostgreSQL and MySQLare 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 fromconnection_id.
• PostgreSQL uses schema, and MySQL uses database, without collapsing bothinto one vague namespace field.
• Real DSNs stay in environment variables, while config files store only theenvironment variable names.
• Query execution passes through sqlglot validation before reaching thedatabase.
• The server accepts only SELECT and WITH ... SELECT, rejects comments andmulti-statement input, and records audit logs for each call.

For MySQL, explain_query(..., analyze=True) is not available in the currentimplementation.

Quick start

If you want to get the server running first and explore the rest later, followthese 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 wantto pin a version. Published release artifacts are also attached to each GitHubRelease.

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 tosql_query_mcp.app:main.

The PyPI install name is sql-query-mcp, and the Python package import path issql_query_mcp.

The default config path is config/connections.json. If you need a differentlocation, 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, usethese 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 stillrequires 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 thesepages.

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

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

License

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