SQL MCP server
Commit Oct 21, 2026Provides a governed SQL gateway for AI agents to access PostgreSQL, MySQL, and OceanBase through controlled relational algebra and strict security policies.
Also known as nethinwei/sql-mcp-server, sql-mcp-server
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.21
- Last commit
- Oct 21, 2026
- License
- MIT
What is SQL MCP?
SQL provides a governed SQL gateway for AI agents to access PostgreSQL, MySQL, and OceanBase through controlled relational algebra and strict security policies.
Summary generated from the project's README
About SQL MCP server
Providing a governed gateway for untrusted AI agents to interact with relational databases is the primary function of this server. It allows developers to connect AI clients like Claude Desktop, Cursor, or VS Code to PostgreSQL, MySQL, and OceanBase instances. Instead of allowing arbitrary SQL, the system uses relational algebra and parameterized code generation to ensure that agents only perform deterministic operations through a whitelist of controlled tools.
Security is enforced through field-level ACLs, row policies, and masking, which prevents unauthorized data exposure. For trusted operators, a specific execute_sql escape channel can be enabled via explicit permissions, though it remains disabled by default. The server manages costs and performance by using EXPLAIN pre-screening, result limits, timeouts, and session budgets. Deployment is handled via Docker Compose or manual builds using Go, and administrators can manage configurations through a dedicated web console.
Written from the project's README. Every use case is checked against a quote from it.
How to install SQL MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall SQL MCP in Claude Code
$ claude mcp add --env 'DATABASE_DSN=<YOUR_DATABASE_DSN>' sql-mcp-server -- docker run -i --rm ghcr.io/nethinwei/sql-mcp-server:0.1.21Install SQL MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"sql-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/nethinwei/sql-mcp-server:0.1.21"
],
"env": {
"DATABASE_DSN": "<YOUR_DATABASE_DSN>"
}
}
}
}Install SQL MCP in VS Code
.vscode/mcp.json
{
"servers": {
"sql-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/nethinwei/sql-mcp-server:0.1.21"
],
"env": {
"DATABASE_DSN": "<YOUR_DATABASE_DSN>"
}
}
}
}Install SQL MCP in VS Code CLI
$ code --add-mcp '{"name":"sql-mcp-server","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/nethinwei/sql-mcp-server:0.1.21"],"env":{"DATABASE_DSN":"<YOUR_DATABASE_DSN>"}}'Install SQL MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"sql-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/nethinwei/sql-mcp-server:0.1.21"
],
"env": {
"DATABASE_DSN": "<YOUR_DATABASE_DSN>"
}
}
}
}Install SQL MCP in Codex
$ codex mcp add sql-mcp-server --env 'DATABASE_DSN=<YOUR_DATABASE_DSN>' -- docker run -i --rm ghcr.io/nethinwei/sql-mcp-server:0.1.21Install SQL MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.sql-mcp-server] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/nethinwei/sql-mcp-server:0.1.21"] [mcp_servers.sql-mcp-server.env] DATABASE_DSN = "<YOUR_DATABASE_DSN>"
Install SQL MCP in Gemini CLI
$ gemini mcp add -s user -e 'DATABASE_DSN=<YOUR_DATABASE_DSN>' sql-mcp-server docker -- run -i --rm ghcr.io/nethinwei/sql-mcp-server:0.1.21Install SQL MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"sql-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/nethinwei/sql-mcp-server:0.1.21"
],
"env": {
"DATABASE_DSN": "<YOUR_DATABASE_DSN>"
}
}
}
}Configuration
DATABASE_DSNSecretDatabase DSN referenced by ${DATABASE_DSN} in config.yaml
| Name | Description | |
|---|---|---|
| DATABASE_DSN | Database DSN referenced by ${DATABASE_DSN} in config.yaml | Secret |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablenethinwei/sql-mcp-server is public and reachablegithub.com/nethinwei/sql-mcp-server ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-21github.com/nethinwei/sql-mcp-server ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSQL MCP Server
The governed SQL gateway for untrusted AI agents.
面向不可信 AI Agent 的受控 SQL 数据访问网关。通过显式 Entity、关系代数 IR 和
参数化 codegen 访问 PostgreSQL、MySQL 与 OceanBase,受治理面不接受任意 SQL,不提供
DDL。可信操作者另有独立的 SQL 逃生通道 execute_sql:默认关闭,只对被显式授予
sql:execute@<数据源> 的用户可见,走单独声明的连接,受硬上限与写入失败即拒绝的
审计约束(见安全模型)。
核心差异
- 确定性执行:Agent 只能组合受控工具和白名单 IR;
- 字段与行治理:RBAC、字段 ACL、row policy 和 mask 统一强制;
- 成本可控:EXPLAIN 预筛、结果上限、超时和 session/tenant 预算;
- 默认拒绝:安全能力无法证明时 fail closed;
- 可审计:配置热重载、异步审计和 OpenTelemetry hook。
运行时安全行为以安全模型为准;Provider 验证边界与证据层级 以兼容矩阵为准;威胁、控制与剩余风险见 威胁模型。所有对外声明的证据汇总见 架构、安全边界与证据索引。不以本页摘要为准。
五分钟体验
只需 Docker 与 Docker Compose:
docker compose -f examples/quickstart/compose.yaml up -d --wait
curl -fsS http://127.0.0.1:8080/healthz
完整的 MCP Inspector 调用、tenant 隔离、mask 和拒绝场景见 五分钟快速体验。
安装与接入
源码构建要求 Go 1.26.10+ 和一个已验证数据库版本:
git clone https://github.com/nethinwei/sql-mcp-server.git
cd sql-mcp-server
make build
- Cursor、Claude Desktop 和 VS Code 的 stdio 模板:
examples/clients/(核对结论见 客户端接入核对); - 完整配置模板:
examples/config.example.yaml; - CLI、启动、热重载、容器部署和升级:运行与运维;
- Web 管理控制台与 Docker Compose 部署:管理控制台;
- 魔搭分发展示:ModelScope 上架与使用。
按角色阅读
首次体验与集成
- 五分钟快速体验:唯一完整 Demo 与 Inspector 示例;
- 配置参考:公开 YAML 配置的唯一事实源;
- Provider 兼容性与 支持版本:当前能力和验证边界。
部署与安全
- 运行与运维:CLI、容器部署、生命周期、监控和升级;
- 管理控制台:配置编辑、发布回滚、管理员权限与 Docker 部署;
- 安全模型:运行时安全行为的唯一事实源;
- 威胁模型:威胁、控制、测试证据与剩余风险;
- SECURITY.md:漏洞披露流程。
开发与维护
版本与规划
- 当前 GA:
v0.1.21(发布说明); - 全版本摘要:CHANGELOG;历史能力与迁移: 发布说明索引;
- 未发布产品规划:Roadmap;
- 数据库候选:Provider Roadmap。
许可
SQL MCP questions
How do I add SQL MCP to Claude Code?
Run claude mcp add --env 'DATABASE_DSN=<YOUR_DATABASE_DSN>' sql-mcp-server -- docker run -i --rm ghcr.io/nethinwei/sql-mcp-server:0.1.21 in your terminal. Add --scope user to make it available in every project.
How do I add SQL MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Which databases are supported?
The server supports PostgreSQL, MySQL, and OceanBase.
How can a trusted operator execute raw SQL?
Trusted operators can use a separate SQL escape channel called execute_sql, which is disabled by default and requires explicit permission.
What security measures are in place for data access?
The server enforces RBAC, field ACLs, row policies, and masking.