mcp-sqlserv

MCP-сервер для безопасного чтения базы данных SQL Server — защита от SQL-инъекций по построению, управляется через Web Admin UI.

Zero raw SQL · Default deny · Bind parameter 100% · Полный аудит

О проекте

mcp-sqlserv позволяет AI-агентам (Claude, Cursor, Claude Code, любой MCP-клиент) читать базы данных SQL Server безопасно и под полным контролем:

• Все запросы формируются на сервере структурно — AI никогда не пишет сырой SQL.

• Идентификаторы (таблицы/колонки) проверяются по реальным метаданным базы данных (sys.tables, sys.columns).

• Значения всегда передаются как bind parameter → SQL-инъекции исключены по построению.

• Разрешения на таблицы работают по принципу default deny: без явного разрешения таблица недоступна.

• Каждый запрос фиксируется в журнале аудита с ключом, инструментом, фильтром, количеством строк и длительностью.

Related MCP server: SQL Server MCP

Возможности

Архитектура

┌──────────────┐   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.

Переменные окружения

Сценарий использования

1. Войдите в Web UI → меню Подключение БД → заполните host/port/user/pass/database + Проверка соединения.

   Для Docker-контейнера: SQL Server на хосте можно использовать через host.docker.internal.

2. Меню API Keys → создайте ключ (показан один раз, сохраните!).

3. Меню Разрешения таблиц → отметьте таблицы, которые AI может читать → Сохранить разрешения. Действует default deny.

4. Подключите AI-агент к https://<domain>/mcp + заголовок Authorization: Bearer <api-key>.

Подключение универсального MCP-клиента

{
  "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"}}}'

Claude Custom Connector (claude.ai / Desktop)

1. Откройте Customize → Connectors → Add custom connector.

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

3. Advanced settings → заполните OAuth Client ID + Secret из меню OAuth Clients
   (redirect URI: https://claude.ai/api/mcp/auth_callback).

   Можно оставить пустым — Claude зарегистрируется автоматически через Dynamic Client Registration (RFC 7591).

4. Нажмите Add → Connect → браузер откроет страницу входа оператора → Разрешить доступ.

5. Claude сохранит refresh token и будет вызывать MCP-инструменты с bearer-токеном.

Claude Code (CLI):

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

Эндпоинты OAuth

Идентичность OAuth = сессия оператора. Access token сопоставляется с внутренним API-ключом oauth:<client_id> — все права на таблицы, ограничение запросов и аудит действуют и для подключений Claude. Отзыв клиента мгновенно аннулирует все его токены.

Инструменты MCP

Имена таблиц должны быть без уточнения схемой (users, не dbo.users). Колонки проверяются по sys.columns; значения на 100% передаются через bind parameter.

Поддерживаемые структурированные фильтры: eq, neq, lt, lte, gt, gte, like, startsWith, endsWith, in, between, isNull, isNotNull.

Безопасность

• Сырой SQL — запрещён — только структурированный построитель запросов

• Важный список идентификаторов — регулярные выражения + проверка реальных метаданных БД

• Default deny — таблицы без разрешения недоступны

• Жёсткие ограничения — максимум 1000 строк/запрос, 20 фильтров, 50 значений IN, тайм-аут 30 сек

• API-ключ + rate limit — на каждый ключ + журнал аудита всех запросов

• Read-only — рекомендация: для SQL Server достаточно выдать пользователю GRANT SELECT

• Пароли БД хранятся зашифрованными AES-256-GCM в SQLite

Развёртывание

Разворачивается через Docker Compose в сеть app-network вместе с nginx в роли обратного прокси (wildcard SSL, без буферизации SSE, CORS для веб-MCP-клиентов).

Миграция между VPS

Код и Docker будут работать на любом VPS, но два следующих элемента не попадают в систему контроля версий (они в .gitignore) и должны переноситься вручную:

# 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/ сервер продолжит работать — нужно будет просто заново указать подключение к БД, создать API-ключи и настройить права таблиц через Web UI.

Структура проекта

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

REST API администратора

Тестирование

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 запускает свой сервер на порту 4000 (каталог данных oauth-test-data/) — дополнительная настройка не требуется.

Участие в разработке

Помощь приветствуется! Открывайте issue или pull request. Для крупных изменений сначала обсудите их через issue, чтобы они соответствовали принципу продукта: безопасность — это продукт — каждый слой (MCP, UI, Agent Test) должен сохранять одинакове стандарты: read-only, default-deny, параметризованные запросы.

Лицензия

Этот проект лицензирован под MIT License.