AI导哈

多数据库查询MCP服务

sql-query-mcp是一个通用的MCP服务器，允许AI在明确的边界内与多个数据库交互，支持数据库发现、受控查询工作流、异步只读查询等功能。

  • by andyWang1688
  • Python
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 andyWang1688/postgres-query-mcp

使用说明

sql查询mcp

中文版

一个通用的MCP服务器，允许人工智能与内部的多个数据库协同工作 清晰的边界。

当前数据库支持

数据库 状态 当前可用性
PostgreSQL 支持 今天可用
MySQL 支持 今天可用
Hive 支持 今天可用
SQLite 候选 尚不支持
SQL Server 候选 尚不支持
ClickHouse 候选 尚不支持

产品价值

sql-query-mcp 帮助AI客户端发现模式、示例数据并进行分析 通过一个受控的MCP接口进行只读查询。

它保留了连接处理、命名空间规则、SQL验证和审计 在服务器端登录，这样您就可以向AI公开有用的数据库上下文 而不会暴露原始连接字符串或简化特定于引擎的概念。

AI能用它做什么

当前的工具集侧重于数据库发现、受控查询工作流、数据库管理和数据库管理， 异步只读查询、批量查询结果导出和一个窄 本地文件导入路径。你可以用它来帮助人工智能助手理解 结构在生成SQL、运行有界查询、启动长时间运行的 只读查询，将PostgreSQL或MySQL结果导出到本地文件，或导入 将准备好的CSV/XLSX文件放入现有表中。

MySQL和Hive支持 explain_query.Hive使用 EXPLAIN 和 EXPLAIN ANALYZE 为了 explain_query.

工具 PostgreSQL MySQL Hive 用途
list_connections() Yes Yes Yes 列出已配置的连接
list_schemas(connection_id) 是 否 否 列出可见的PostgreSQL模式
list_databases(connection_id) 否 是 是 列出可见的MySQL或Hive数据库
list_tables(connection_id, schema?, database?) 是 是 是]列出表和视图
describe_table(connection_id, table_name, schema?, database?) Yes Yes Yes 检查列、键和索引
run_select(connection_id, sql, limit?) Yes Yes Yes 运行简短的有界只读查询
start_query(connection_id, sql, limit?) Yes Yes Yes 启动长时间运行的只读查询
get_query(query_id, offset?, limit?) Yes Yes Yes 获取异步查询状态和分页结果
cancel_query(query_id) Yes Yes Yes 取消运行异步查询
explain_query(connection_id, sql, analyze?) 是 是 是]检查查询计划
get_table_sample(connection_id, table_name, schema?, database?, limit?) 是 是 是]获取小桌子样本
export_query_file(connection_id, sql, output_path, format?, limit?, export_all?, file_name?, overwrite?) 是 是 否 将查询结果导出到本地CSV/XLSX文件
import_table_file(connection_id, table_name, file_path, schema?, database?, sheet_name?) 是 是 是]导入本地CSV/XLSX文件

这些工具对于列出名称空间、检查表等任务非常有用 定义、审核索引、采样记录、运行简短只读 查询与 run_select，使用运行长只读查询 start_query, get_query，以及 cancel_query，使用分析只读查询 EXPLAIN，以及 将PostgreSQL或MySQL查询结果导出到本地CSV/XLSX文件。你可以 还可以导入准备好的本地文件。有关完整的请求和响应详细信息，请参阅 docs/api-reference.md （中文）。

边界如何受到约束

如今，产品边界有意变窄。PostgreSQL、MySQL和Hive 今天可以买到。查询工具保持只读，PostgreSQL和MySQL查询 结果可以导出到本地文件，唯一的数据库写入路径是 受控的本地CSV/XLSX导入到现有表中。

该服务通过多种方式明确地保持这些边界。

  • 连接声明 engine 显式地，因此服务器永远不会猜测 connection_id.
  • PostgreSQL使用 schema，而MySQL和Hive使用 database，没有 将两者合并为一个模糊的名称空间字段。
  • 真正的DSN保留在环境变量中，而配置文件仅存储 环境变量名称。
  • 查询执行通过 sqlglot 在到达之前进行验证 数据库。使用 run_select 用于简短的有界只读查询，并使用 start_query, get_query，以及 cancel_query 用于长时间运行的只读 查询。
  • 服务器只接受 SELECT 和 WITH ... SELECT，拒绝评论和 并记录每次呼叫的审计日志。
  • export_query_file 在MCP服务器计算机上写入文件。它是同步的 而是批量读取数据库行并写入CSV/XLSX文件。大型出口可以 仍然达到MCP客户端的工具超时时间。对于XLSX输出，UUID值为 写为文本和时区感知的日期时间值时没有 时区。目前尚不支持Hive导出。
  • import_table_file 不接受原始SQL。它仅插入以下文件列 标题与现有表列完全匹配。
  • 蜂巢 import_table_file 仅适用于小文件，拒绝文件 具有1000多个数据行。Hive导入逐一写入行，因此它们 可能很慢，并且可能会碰到MCP客户端的工具超时。对于批量Hive负载， 使用Hive原生 LOAD DATA、外部表或您现有的数据摄取 管道。

对于Hive， explain_query 用途 EXPLAIN 和 EXPLAIN ANALYZE.

快速开始

sql-query-mcp 支持两种基于PyPI的官方设置模式。两者都是有意的 用于实际使用，而不仅仅是本地测试。

  1. 选择您希望MCP客户端如何启动服务器。

如果你想在一个命令后使用一个简单的本地命令，请使用已安装的命令模式 安装。

pipx install sql-query-mcp

如果要在中直接声明包源，请使用托管启动模式 您的MCP客户端配置。

pipx run --spec sql-query-mcp sql-query-mcp

将版本固定为 pipx install 'sql-query-mcp==X.Y.Z' 或 pipx run --spec 'sql-query-mcp==X.Y.Z' sql-query-mcp已安装升级 命令模式 pipx upgrade sql-query-mcp.

  1. 创建一个配置文件。

服务器配置应位于存储库之外，因此相同的文件 适用于任一启动模式。

mkdir -p ~/.config/sql-query-mcp

然后将本节稍后的示例JSON另存为 ~/.config/sql-query-mcp/connections.json.

  1. 在MCP客户端中注册服务器。
  • 食品法典： docs/codex-setup.md （中文）
  • OpenCode： docs/opencode-setup.md （中文）

已安装的命令模式意味着您的客户端正在运行 sql-query-mcp 直接。 托管启动模式意味着您的客户端通过以下方式启动服务器 pipx run.

在这两种模式下，放入 SQL_QUERY_MCP_CONFIG 以及您的真实数据库DSN MCP客户端的环境块，而不是在shell中导出它们。

控制台入口点为 sql-query-mcp，映射到 sql_query_mcp.app:main.

PyPI安装名称为 sql-query-mcp，Python包导入路径为 sql_query_mcp.

对于 pipx install 和 pipx run，set SQL_QUERY_MCP_CONFIG 明确地 您的配置文件路径。默认 config/connections.json 路径主要用于 源代码检查和本地开发。

示例配置如下。

{
  "settings": {
    "default_limit": 200,
    "max_limit": 1000,
    "audit_log_path": "logs/audit.jsonl"
  },
  "connections": [
    {
      "connection_id": "crm_prod_main_ro",
      "engine": "postgres",
      "label": "CRM PostgreSQL production / Main / read-only",
      "env": "prod",
      "tenant": "main",
      "role": "ro",
      "dsn_env": "PG_CONN_CRM_PROD_MAIN_RO",
      "enabled": true,
      "default_schema": "public"
    },
    {
      "connection_id": "crm_mysql_prod_main_ro",
      "engine": "mysql",
      "label": "CRM MySQL production / Main / read-only",
      "env": "prod",
      "tenant": "main",
      "role": "ro",
      "dsn_env": "MYSQL_CONN_CRM_PROD_MAIN_RO",
      "enabled": true,
      "default_database": "crm"
    },
    {
      "connection_id": "warehouse_hive_prod_main_ro",
      "engine": "hive",
      "label": "Warehouse Hive production / Main / read-only",
      "env": "prod",
      "tenant": "main",
      "role": "ro",
      "dsn_env": "HIVE_CONN_WAREHOUSE_PROD_MAIN_RO",
      "enabled": true,
      "default_database": "default"
    }
  ]
}

在MCP客户端环境中设置DSN。对于Hive，使用Hive DSN，例如：

export HIVE_CONN_WAREHOUSE_PROD_MAIN_RO='hive://user:password@hive.example.com:10000/default?auth=CUSTOM'

文档

如果您想了解实施细节、设置指南或内部结构，请使用 这些文档是你的出发点。

  • docs/project-overview.md：项目目标、概念和代码结构（中文）
  • docs/api-reference.md：MCP工具参考（中文）
  • docs/codex-setup.md：Codex设置步骤（中文）
  • docs/opencode-setup.md：OpenCode设置步骤（中文）
  • docs/release-process.md：PyPI和GitHub发布工作流程（中文）
  • docs/git-workflow.md：存储库协作工作流（中文）

发展

如果要在本地修改或验证项目，请使用此最短路径。 可编辑安装仍然是开发路径，本地环境仍然 需要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

主要切入点是 sql_query_mcp/app.py核心模块包括：

  • sql_query_mcp/config.py：配置加载和验证
  • sql_query_mcp/validator.py：只读SQL验证
  • sql_query_mcp/introspection.py：元数据检查
  • sql_query_mcp/executor.py：查询执行和限制
  • sql_query_mcp/adapters/：PostgreSQL、MySQL和Hive适配器

贡献

如果您想贡献或查看存储库工作流，请从以下几点开始 页。

  • CONTRIBUTING.md
  • docs/roadmap.md
  • docs/git-workflow.md （中文）

跑 PYTHONPATH=. python3 -m unittest discover -s tests 提交之前 变化。

许可证

该项目在MIT许可证下发布。看 LICENSE.

相关 MCP