金大哥 - mcp-sql MCP 详情

article

README

🚀 mcp-sql

mcp-sql 是一个 MCP 服务器，它允许大语言模型（LLMs）查询 PostgreSQL、SQLite 和 MySQL 数据库。它是单二进制文件，默认只读，支持多数据库。

🚀 快速开始

你可以按照以下步骤快速使用 mcp-sql。

📦 安装指南

使用以下命令安装 mcp-sql：

cargo install mcp-sql

💻 使用示例

基础用法

# 演示模式 — 使用示例数据立即尝试
mcp-sql --demo

# 单个数据库
mcp-sql --url postgres://user:pass@localhost/mydb

# SQLite
mcp-sql --url sqlite:path/to/db.sqlite

# 多个数据库
mcp-sql --url postgres://localhost/app --url sqlite:analytics.db

# 启用写操作
mcp-sql --url sqlite:local.db --allow-write

# 自定义行限制
mcp-sql --url mysql://user:pass@localhost/shop --row-limit 500

# 从环境变量中读取 URL
mcp-sql --url-env DATABASE_URL

# 混合使用 --url 和 --url-env
mcp-sql --url sqlite:local.db --url-env PROD_DB_URL

# 自定义查询超时时间（默认：30 秒）
mcp-sql --url sqlite:local.db --query-timeout 60

📚 详细文档

Claude Code 配置

claude mcp add sql -- mcp-sql --url sqlite:path/to/your.db

或者直接编辑 ~/.claude.json：

{
  "mcpServers": {
    "sql": {
      "type": "stdio",
      "command": "mcp-sql",
      "args": ["--url", "sqlite:path/to/your.db"]
    }
  }
}

Claude Desktop 配置

在你的 Claude Desktop 配置文件（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）中添加以下内容：

{
  "mcpServers": {
    "sql": {
      "command": "mcp-sql",
      "args": [
        "--url", "postgres://user:pass@localhost/mydb",
        "--url", "sqlite:analytics.db"
      ]
    }
  }
}

Cursor / VS Code 配置

在你的 MCP 配置文件（.cursor/mcp.json 或等效文件）中添加以下内容：

{
  "mcpServers": {
    "sql": {
      "command": "mcp-sql",
      "args": ["--url", "sqlite:path/to/your.db"]
    }
  }
}

工具介绍

| 工具 | 描述 | |------|-------------| | list_databases | 显示所有已连接数据库的名称和类型 | | list_tables | 列出表格及其行数 | | describe_table | 列详细信息：名称、类型、是否可为空、默认值、主键、外键 | | show_create_table | 显示表的 CREATE TABLE DDL 语句 | | show_schema | 所有表及其关系的 Mermaid ER 图 | | list_indexes | 索引名称、列和唯一性约束 | | sample_data | 以 JSON 格式返回表中的示例行（无需 SQL） | | query | 执行 SQL 并以 JSON 格式返回结果 | | explain | 显示查询执行计划 | | query_dry_run | 验证 SQL 并显示查询计划，但不执行 |

当连接多个数据库时，所有工具都接受一个可选的 database 参数。如果只连接了一个数据库，则会自动使用该数据库。

CLI 选项

| 标志 | 默认值 | 描述 | |------|---------|-------------| | --url | — | 数据库连接 URL（可重复） | | --url-env | — | 从环境变量中读取数据库 URL（可重复） | | --demo | false | 使用预加载示例数据的演示 SQLite 数据库启动 | | --allow-write | false | 启用写操作（INSERT、UPDATE、DELETE、CREATE、DROP） | | --row-limit | 100 | 每个查询返回的最大行数 | | --query-timeout | 30 | 查询超时时间（秒） |

至少需要一个 --url 或 --url-env（除非使用 --demo）。

🔧 技术细节

安全性

默认只读 — 只允许 SELECT、WITH、SHOW、PRAGMA 和 EXPLAIN 查询。
强制行限制 — 如果查询中没有 LIMIT，则会自动注入（默认：100）。
查询超时 — 查询在配置的超时时间后会被终止（默认：30 秒）。
凭证隐藏 — 在 list_databases 输出中，密码会被屏蔽。
PostgreSQL/MySQL — 此外，还使用 SET TRANSACTION READ ONLY 进行数据库级别的强制限制。

使用 --allow-write 可启用 INSERT、UPDATE、DELETE、CREATE 和 DROP 操作。

支持的数据库

| 数据库 | URL 方案 | 说明 | |----------|-----------|-------| | PostgreSQL | postgres:// 或 postgresql:// | 完全支持 | | SQLite | sqlite:path 或 sqlite::memory: | 完全支持 | | MySQL | mysql:// 或 mariadb:// | 完全支持 |

📄 许可证

你可以选择遵循 Apache 许可证 2.0 版或 MIT 许可证。

mcp-sql