SQL Query MCP

sql查询mcp

中文版

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

当前数据库支持

产品价值

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

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

AI能用它做什么

当前的工具集侧重于数据库发现、受控查询工作流、数据库管理和数据库管理， 以及一个狭窄的本地文件导入路径。你可以用它来帮助人工智能助手 在生成SQL或导入准备好的CSV/XLSX文件之前了解结构 到现有的表中。

MySQL支持 explain_query，但不是 explain_query(..., analyze=True) 在 目前的实施。

这些工具对于列出名称空间、检查表等任务非常有用 定义、查看索引、采样记录、分析只读查询 随着 EXPLAIN，并导入准备好的本地文件。对于完整的请求和 响应详细信息，请参阅 docs/api-reference.md （中文）。

边界如何受到约束

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

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

• 连接声明 engine 显式地，因此服务器永远不会猜测

connection_id.

• PostgreSQL使用 schemaMySQL使用 database，不会同时坍塌

进入一个模糊的名称空间字段。

• 真正的DSN保留在环境变量中，而配置文件仅存储

环境变量名称。

• 查询执行通过 sqlglot 在到达之前进行验证

数据库。

• 服务器只接受 SELECT 和 WITH ... SELECT，拒绝评论和

并记录每次呼叫的审计日志。

• import_table_file 不接受原始SQL。它仅插入以下文件列

标题与现有表列完全匹配。

对于MySQL， explain_query(..., analyze=True) 当前不可用 实施。

快速开始

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"
    }
  ]
}

文档

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

• 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适配器

贡献

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

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

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

许可证

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