mcp-sqlserv

Servidor MCP para el acceso de solo lectura a bases de datos SQL Server — sin inyección de SQL por construcción, gestionado desde la Web Admin UI.

Zero raw SQL · Default deny · Bind parameter 100% · Auditoría completa

Acerca de

mcp-sqlserv permite que los agentes de IA (Claude, Cursor, Claude Code, cualquier cliente MCP) lean de forma segura y controlada bases de datos SQL Server:

• Todas las consultas se construyen de manera estructurada por el servidor: la IA nunca escribe SQL en bruto.

• Los identificadores (tablas/columnas) se validan contra los metadatos reales de la base de datos (sys.tables, sys.columns).

• Los valores son siempre bind parameters → la inyección de SQL es imposible por construcción.

• Los permisos por tabla son de denegación por defecto: sin un permiso explícito, la tabla no se puede tocar.

• Cada solicitud queda registrada en el registro de auditoría, con clave, herramienta, filtro, número de filas y duración.

Related MCP server: safedb-mcp

Características

Arquitectura

┌──────────────┐   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 │    │
                                                      └──────────────┴──────────┴────┘

Inicio rápido

# 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

El servidor se ejecuta en http://localhost:4000: la interfaz de administración está en / y el endpoint MCP en /mcp.

Variables de entorno

Nota: La fila de OAUTH_REFRESH_TTL_S modificamos el valor. Debería ser 2592000 sin (segundos). Reviso.

Rehago la fila:

| OAUTH_REFRESH_TTL_S | 2592000 | Tiempo de vida del refresh token (segundos, 30 días) |

Flujo de uso

1. Inicia sesión en el Web UI → menú Conexión DB → completa host/puerto/usuario/contraseña/base de datos + Test Connection.

   En contenedores Docker, se puede usar el SQL Server del host mediante host.docker.internal.

2. Menú API Keys → genera una clave (se muestra una sola vez, consérvala).

3. Menú Permisos de tablas → marca las tablas que la IA puede leer → Guardar permisos. Denegación por defecto.

4. Conecta tu agente de IA en https://<dominio>/mcp + cabecera Authorization: Bearer <api-key>.

Conectar el cliente MCP a generic

{
  "mcpServers": {
    "sql-server": {
      "url": "https://<domain>/mcp",
      "headers": { "Authorization": "Bearer sk-xxxx" }
    }
  }
}

Prueba rápida con 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"}}}'

Conector personalizado de Claude (claude.ai / Desktop)

1. Abre Customize → Connectors → Add custom connector.

2. Remote MCP server URL: https://<dominio>/mcp.

3. En Advanced settings → introduce OAuth Client ID + Secret desde el menú OAuth Clients (URL de redirect: https://claude.ai/api/mcp/auth_callback).

   Puede dejarse vacío: Claude se registra automáticamente mediante Dynamic Client Registration (RFC 2591).

4. Haz clic en Add → Connect: el navegador abre la página de login del operador → Permitir acceso.

5. Claude guarda el refresh token y llama a la herramienta MCP con un bearer token.

Claude Code (CLI):

claude mcp add mcp-sqlserv https://<domain>/mcp --transport http \
  ... # bila client pre-registered: --client-id <id> --client-secret --callback-port

Endpoints OAuth

La identidad OAuth es la sesión del operador. El access token mapea a una API key interna oauth:<client_id>: todos los permisos de tabla, límites de petición y auditoría se aplican también a la conexión de Claude. Revocar un cliente anula inmediatamente todos los tokens de ese cliente.

Herramientas MCP

Los nombres de las tablas deben ir sin prefijo de esquema (users, no dbo.users). Las columnas son validadas contra sys.columns; the valores están 100% parametrizados.

Los filtros estructurados soportados: eq, neq, lt, lte, gt, gte, like, startsWith, endsWith, in, between, isNull, isNotNull.

Seguridad

• Cero SQL en bruto desde la IA — solo builder de consultas estructurado

• Identifier allowlist — regex y verificación de los metadatos reales de la base de datos

• Default deny — no se puede acceder a una tabla sin permiso

• Límite estricto — máximo 1000 filas por consulta, 20 filtros, 50 valores en IN, timeout de 30

• API key + rate limit por clave + log de auditoría en todas las request

• Solo lectura: se recomienda que el dato de SQL Server for el que se usa sea GRANT SELECT

• La contraseña de la base de datos se guarda con cifrado AES-256-GCM en SQLite

Despliegue

Despliegue con Docker Compose en la red app-network junto a nginx como reverse proxy (SSL wildcard, SSE sin buffer, CORS para clientes MCP).

Migración entre VPS

El código y Docker funcionarán en cualquier VPS, pero las siguientes dos no se suben a Git (están en .gitignore) y deben migrarse manualmente:

# 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

Sin migración de data/, el servidor sigue funcionando — solo se debes configurar de nuevo la conexión de BD, los API keys y los permisos de tabla desde la Web UI.

Estructura del proyecto

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

API REST Admin

Testing

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, revoke

test/oauth.mjs inicia su propio servidor en el puerto 4100 (directorio de datos oauth-test-data/) — no necesita configuración adicional.

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, revive un issue o un pull request. Para cambios importantes, plantéalo primero en un issue para alinear con el principio del producto: la seguridad es el producto — cada superficie (MCP, interface, Agent Test) debe mantener el mismo estándar: solo escritura, denegación por defecto y ejecución parametrizada.

Licencia

Este proyecto está bajo la MIT License.