MCP Server 用于只读访问 SQL Server 数据库——从构造上防止 SQL 注入，通过 Web Admin UI 管理。
零原始 SQL · 默认拒绝 · 绑定参数 100% · 完整审计
mcp-sqlserv 让 AI 代理（Claude、Cursor、Claude Code 以及任何 MCP 客户端）能够安全、受控地读取 SQL Server 数据库：
所有查询都由服务器结构化构建——AI 从不编写原始 SQL。
标识符（表/列）会对照数据库真实元数据（sys.tables、sys.columns）进行验证。
值始终通过绑定参数传递 → SQL 注入在构造上不可能发生。
表级权限采用默认拒绝：没有显式授权，表就无法被访问。
每个请求都会记录到审计日志中，包含 key、工具、筛选条件、行数和耗时。
Related MCP server: SQL Server MCP
功能 | 说明 |
MCP Streamable HTTP | 端点 |
多项目 | 每个项目独立的 URL |
API Key | 按 AI 使用者创建 / 撤销 key |
OAuth 2.1 | Authorization Code + PKCE、DCR（RFC 7591）、刷新令牌轮换、撤销 |
SQL Server 连接 | 主机/端口/用户名/密码（AES-256-GCM 加密），TLS 可选 |
细粒度授权 | 按表：读取数据和/或查看元数据。默认 = DENY |
审计日志 | 记录所有 AI 请求：key、工具、表、筛选、行数、耗时、状态 |
速率限制 | 每个 API key 60 req/min（可配置） |
完全只读 | 工具只生成 |
Agent 测试 | 直接从 Web UI 与 Gemini 模型对话，进行端到端测试 |
┌──────────────┐ HTTPS ┌─────────────┐ ┌──────────────────────────────┐
│ AI Agent ├───────────►│ nginx ├─────────►│ mcp-sqlserv (Docker) │
│ (MCP client)│ Bearer │ reverse │ app-net │ Express + MCP + OAuth │
└──────────────┘ token │ proxy+SSL │ work │ │ │ │
└─────────────┘ │ ▼ ▼ │
┌──────────────┐ HTTPS │ SQLite mssql pool │
│ Web Admin UI ├─────────────────────────────────────►│ (data/, keys, │ │
│ (browser) │ REST /api/* │ audit, izin) ▼ │
└──────────────┘ │ ┌──────────┐ │
│ │ SQL Srvr │ │
└──────────────┴──────────┴────┘# 1. Clone & siapkan environment
git clone https://github.com/<username>/mcp-sqlserv.git
cd mcp-sqlserv
cp .env.example .env # isi ADMIN_USER / ADMIN_PASSWORD (min 8 karakter)
# 2. Build & jalankan
docker compose up -d --build
# 3. Verifikasi
curl http://localhost:4000/healthz服务器运行在 http://localhost:4000——Web UI 管理后台位于 /，MCP 端点位于 /mcp。
变量 | 默认值 | 说明 |
|
| 服务器端口 |
|
| SQLite 数据目录（在 compose 中挂载为卷） |
|
| 管理员 Web UI 用户名 |
| 必填 | 管理员 Web UI 密码（至少 8 个字符） |
| 自动 | JWT/加密密钥（留空时自动生成并持久化） |
|
| SQL 查询超时时间 |
|
| 每个 API key 的速率限制 |
|
| 设为 |
|
| Authorization Code 有效期（秒） |
|
| Access Token 有效期（秒） |
|
| Refresh Token 有效期（秒，30 天） |
登录 Web UI → 菜单 Koneksi DB → 填写主机/端口/用户名/密码/数据库 + 测试连接。
对于 Docker 容器，可通过
host.docker.internal连接宿主机上的 SQL Server。
菜单 API Keys → 创建 key（只显示一次，请保存好！）。
菜单 表权限（Izin Tabel）→ 勾选允许 AI 读取的表 → 保存权限。默认为拒绝。
将 AI 代理连接到 https://<domain>/mcp，并携带请求头 Authorization: Bearer <api-key>。
{
"mcpServers": {
"sql-server": {
"url": "https://<domain>/mcp",
"headers": { "Authorization": "Bearer sk-xxxx" }
}
}
}用 curl 快速测试：
curl -X POST https://<domain>/mcp \
-H "Authorization: Bearer sk-xxxx" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'打开 Customize → Connectors → Add custom connector。
填写 远程 MCP server URL：https://<domain>/mcp。
Advanced settings → 从 OAuth Clients 菜单中填写 OAuth Client ID + Secret
（重定向 URI：https://claude.ai/api/mcp/auth_callback）。
也可以留空——Claude 会通过 Dynamic Client Registration（RFC 7591）自动注册。
点击 Add → Connect → 浏览器打开操作员登录页面 → 点击 允许访问。
Claude 会保存刷新令牌，并使用 bearer token 调用 MCP 工具。
Claude Code（CLI）：
claude mcp add mcp-sqlserv https://<domain>/mcp --transport http \
... # bila client pre-registered: --client-id <id> --client-secret --callback-port端点 | 标准 |
| RFC 9728 |
| RFC 8414 |
| RFC 7591 (DCR, public + confidential) |
| RFC 6749 + PKCE S256 |
| RFC 6749 / RFC 7636 |
| RFC 7009 |
OAuth 身份 = 操作员会话。Access token 会映射到内部 API key oauth:<client_id>——所有表权限、速率限制和审计同样适用于 Claude 连接；撤销客户端会立即吊销该客户端的全部令牌。
工具 | 功能 |
| 列出已授权表 + 估算行数 |
| 字段、类型、是否可空、是否自增、主键、索引 |
| 使用结构化筛选、排序和分页读取记录 |
| 使用可选筛选条件统计行数 |
| 通过主键获取 1 行 |
| 服务器 / 数据库信息 |
表名不需要 schema 前缀（使用 users，而不是 dbo.users）。列会根据 sys.columns 进行验证；值 100% 通过绑定参数传递。
支持的结构化筛选器：eq、neq、lt、lte、gt、gte、like、startsWith、endsWith、in、between、isNull、isNotNull。
来自 AI 的零原始 SQL——只有结构化查询构建器
标识符白名单——正则表达式 + 对真实数据库元数据的验证
默认拒绝——没有授权的表无法访问
硬限制——每次查询最多 1000 行、最多 20 个筛选、最多 50 个 IN 值、超时 30 秒
API key + 频率限制——每个 key 都有速率限制，并且所有请求都会记录审计日志
只读——建议数据库用户仅使用 SQL Server 只读账号：仅授予 GRANT SELECT 权限
数据库密码以 AES-256-GCM 加密后存储在 SQLite 中
使用 Docker Compose 在 app-network 网络中部署，并通过 nginx 反向代理（SSL 通配符、SSE 非缓冲、为 MCP Web 客户端开启 CORS）对外提供服务。
代码和 Docker 可以在任意 VPS 上自动运行，但以下两个目录不会包含在 Git 中，需要进行手动迁移：
需要迁移的内容 | 内容说明 | 操作说明 |
| 管理员凭据和 secret 密钥 | 从旧 VPS 中复制该文件，或根据 |
| SQLite（API key、权限、审计日志、数据库连接） | 从旧 VPS |
# Di VPS baru
git clone https://github.com/<username>/mcp-sqlserv.git && cd mcp-sqlserv
# Migrasi state dari VPS lama (opsional)
rsync -av vps-lama:/path/mcp-sqlserv/.env .env
rsync -av vps-lama:/path/mcp-sqlserv/data ./data
# Network eksternal harus ada dulu (dipakai docker-compose.yaml)
docker network create app-network # abaikan jika sudah ada
docker compose up -d --build如果不迁移
data/目录，服务器依然可以正常运行——只需通过 Web UI 重新配置数据库连接、API key 和表权限即可。
mcp-sqlserv/
├── src/
│ ├── index.ts # Bootstrap Express + routing
│ ├── config.ts # Env config
│ ├── db/storage.ts # SQLite: api_keys, db_config, permissions, audit_log
│ ├── sqlserver/ # Connection pool, metadata (sys.tables), query builder
│ ├── mcp/ # MCP server (per-session) + tools
│ ├── oauth/ # OAuth 2.1: router, PKCE, discovery
│ ├── api/ # REST admin (auth, config, keys, permissions, audit)
│ └── ui/ # SPA vanilla JS (public/)
├── public/ # Web UI admin (tanpa build step)
├── test/ # Test suite keamanan + OAuth + smoke
├── Dockerfile # Multi-stage build (node:20-alpine)
├── docker-compose.yaml # Attach ke app-network, host.docker.internal
└── LICENSE # MIT方法 | 路径 | 说明 |
POST |
| 管理员登录（httpOnly cookie） |
GET |
| 数据库、key 和权限状态 |
GET/PUT |
| 读取 / 保存数据库配置 |
POST |
| 测试数据库连接 |
GET/POST |
| 列出 / 创建 API key |
PUT/DELETE |
| 重命名 / 撤销 key |
GET/PUT |
| 列出 / 保存表权限 |
GET |
| 审计日志 |
GET |
| MCP URL 信息 + 配置示例 |
GET |
| 健康检查（无需认证） |
npm run test:smoke # smoke test dasar
npm run test:security # 29 test: injection, permission, limit, pagination, auth
npm run test:oauth # 46 test: discovery, DCR, PKCE, consent, token, refresh, revoketest/oauth.mjs 会在 4100 端口（数据目录 oauth-test-data/）启动自己的服务器——无需额外配置。
欢迎贡献！请提交 issue 或 pull request。对于重大改动，请先通过 issue 讨论，以确保其符合产品原则：安全即是产品——每一个表面（MCP、UI、Agent Test）都必须保持同样的标准：只读、默认拒绝、参数绑定。
本项目基于 MIT License 许可。
Guard AI agents' PostgreSQL/MySQL access via MCP: SQL audit, auth, masking, write approval
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
