使用说明
⚠️ 项目未维护和未发布
注意： 此项目不再维护。相应的npm包已从npm注册表中永久取消发布，不再可供下载。
sql-mcp
用于SQL数据库的MCP（模型上下文协议）服务器，内置有防止破坏性操作的护栏。
AI编码代理可以自主执行SQL查询，这意味着它们也可能意外运行 DELETE, DROP，或 UPDATE 在错误的行。 sql-mcp 位于代理和数据库之间，拦截受保护的操作，并在执行之前要求明确确认。
支持的数据库：微软SQL Server、PostgreSQL
安装
⚠️ 包已删除
此包已从npm中删除，不再可用于安装。 此存储库仅供参考。以下命令将不再工作。
# Run directly without installing
npx sql-mcp
# Or install globally
npm install -g sql-mcp
sql-mcp
配置
sql-mcp 完全通过环境变量进行配置——可以在shell中，也可以在MCP客户端的配置中。
必需
| 变量 | 描述 |
|---|---|
DB_TYPE |
数据库类型： mssql 或 pgsql |
DB_HOST |
数据库服务器主机名 |
DB_NAME |
数据库名称 |
DB_USER |
数据库用户名 |
DB_PASSWORD |
数据库密码 |
可选的
| 变量 | 默认值 | 描述 |
|---|---|---|
DB_PORT |
5432 （pgsql）/ 1433 （mssql） |
数据库端口 |
GUARD_MODE |
confirm |
confirm --保留谨慎的查询以供批准。 block --彻底拒绝他们 |
GUARDED_OPERATIONS |
请参阅下文 | 逗号分隔的SQL关键字以进行保护。 NONE 禁用防护。 ALL 使用完整的默认列表 |
DB_TRUST_SERVER_CERTIFICATE |
false |
仅限MSSQL。设为 true 对于具有自签名证书的本地/dev实例 |
默认保护操作: INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, EXEC, EXECUTE, MERGE, CREATE, GRANT, REVOKE, DENY
MCP客户端设置
克劳德代码/光标/风帆
添加到MCP设置中（例如。 ~/.claude/settings.json 或您客户的同等职位）：
PostgreSQL：
{
"mcpServers": {
"database": {
"command": "npx",
"args": ["sql-mcp"],
"env": {
"DB_TYPE": "pgsql",
"DB_HOST": "localhost",
"DB_NAME": "mydb",
"DB_USER": "postgres",
"DB_PASSWORD": "secret"
}
}
}
}
SQL服务器：
{
"mcpServers": {
"database": {
"command": "npx",
"args": ["sql-mcp"],
"env": {
"DB_TYPE": "mssql",
"DB_HOST": "localhost",
"DB_NAME": "mydb",
"DB_USER": "sa",
"DB_PASSWORD": "secret",
"DB_TRUST_SERVER_CERTIFICATE": "true"
}
}
}
}
防护模式
confirm （默认）
当检测到防护操作时， sql-mcp 保存查询并返回一个令牌。代理人必须致电 confirm_query 使用该令牌执行它。这使您有机会在任何运行之前进行审查和批准。
Agent: run_query("DELETE FROM users WHERE inactive = true")
← { needs_confirmation: true, token: "uuid", query: "...", expires_in_minutes: 5 }
[You review and approve]
Agent: confirm_query("uuid")
← { success: true, rowsAffected: [47] }
令牌在以下时间到期 5分钟。如果令牌过期，请重新运行原始查询以获取新的令牌。
“运行所有内容”/自动批准代理模式的注意事项：如果您的MCP客户端配置为自动执行工具调用，而不会暂停供人查看（例如Cursor的“运行一切”模式），则代理可能会调用
confirm_query立即之后run_query没有任何人工检查点。在这种情况下，confirm模式不提供真正的保护--使用block取而代之的是模式。
block
所有受保护的操作都会立即被拒绝，无法确认。将其用于生产环境或任何代理自主运行而无需人工审查的设置。
工具
list_tables
列出连接数据库中的所有用户表。
退货：每个表的架构名称、表名称、行数、大小（MB）。
{
"success": true,
"table_count": 12,
"tables": [
{ "schema": "public", "table": "users", "full_name": "public.users", "row_count": 15234, "size_mb": 45.2 }
]
}
describe_table
返回表的详细架构信息。
参数:
tableName--表名，可选模式前缀（例如。"users"或"dbo.users")
退货：列（具有类型、可空性、默认值、PK/标识标志）、外键、索引、行数和示例行。
{
"success": true,
"table": "public.users",
"statistics": { "row_count": 15234 },
"columns": [
{ "name": "id", "type": "integer", "nullable": false, "default": null, "primary_key": true, "identity": true },
{ "name": "email", "type": "character varying(255)", "nullable": false, "default": null, "primary_key": false, "identity": false }
],
"foreign_keys": [ ... ],
"indexes": [ ... ],
"sample_rows": [ ... ]
}
run_query
执行SQL查询。
参数:
sql--要运行的SQL查询
安全（无保护）查询立即执行并返回结果。根据配置的查询处理受保护的查询 GUARD_MODE.
结果上限为 1000行如果结果集被截断，则响应包括 "truncated": true.
confirm_query
执行以前保存的受保护查询。
参数:
token--由返回的UUID令牌run_query
仅当令牌存在且未过期（5分钟TTL）时才有效。
analyze_query_impact
在不执行破坏性SQL查询的情况下对其进行分析。返回受影响的行数、将在子表上触发的任何CASCADE关系、警告和建议的估计值。
参数:
sql--要分析的SQL查询(DELETE,UPDATE,TRUNCATE，或DROP)
退货：操作类型、目标表、受影响的估计行、级联详细信息、警告和建议。
{
"operation": "UPDATE",
"table": "public.orders",
"estimated_rows_affected": 3200,
"cascades": [],
"warnings": [],
"recommendations": [
"Large operation (3,200 rows). Consider batching with LIMIT to reduce lock duration."
]
}
给 DELETE, TRUNCATE，以及 DROP，响应还包括 cascades --儿童桌有 ON DELETE CASCADE 外键与目标表的关系。级联行数是最好的努力，可能 null 对于复杂的查询。
备注：In
confirm模式，run_query当持有受保护的查询时，会自动在其响应中包含影响分析——您不需要调用analyze_query_impact单独。
需求
- Node.js≥18
- 对数据库的网络访问
许可证
麻省理工学院
