MSSQL-MCP

Microsoft SQL Server için güvenlik öncelikli, salt-okunur MCP (Model Context Protocol) sunucusu.

Security-first, read-only MCP (Model Context Protocol) server for Microsoft SQL Server.

🇹🇷 Türkçe · 🇬🇧 English

---

🇹🇷 Türkçe

Bu proje nedir?

MSSQL-MCP, LLM'leri (Claude gibi) kurumsal Microsoft SQL Server veritabanlarına güvenle bağlamak için tasarlanmış bir MCP sunucusudur. LLM doğal dil sorusunu SQL'e çevirir, MSSQL-MCP bu SQL'i katmanlı güvenlik filtrelerinden geçirip yalnızca okuma amaçlıysa çalıştırır.

Neden? — LLM'i veritabanına doğrudan bağlamanın riskleri

Bir LLM'e veritabanı erişimi vermek güçlüdür ama tehlikelidir:

• LLM yanlışlıkla (veya prompt injection ile kasıtlı olarak) DELETE, UPDATE, DROP gibi yıkıcı sorgular üretebilir.
• "Salt-okunur olduğunu varsaydığınız" kullanıcı, fark etmediğiniz bir GRANT yüzünden yazma yetkisine sahip olabilir.
• Sınırsız bir SELECT bile milyonlarca satır çekip sunucuyu kilitleyebilir.
• xp_cmdshell, OPENROWSET gibi kapılar veritabanının çok ötesine geçer.

Güvenlik felsefesi: salt-okunur doğrulama + savunma derinliği

MSSQL-MCP tek bir güvenlik katmanına güvenmez:

Katman 1 — Başlangıçta aktif salt-okunurluk doğrulaması. Sunucu açılırken bağlanan kullanıcının salt-okunur olduğunu aktif olarak kanıtlamasını ister. Üç bağımsız kontrolün TÜMÜ geçmelidir:

Kontrol	Nasıl	Neden
Sunucu rolleri	IS_SRVROLEMEMBER: sysadmin, serveradmin, dbcreator, securityadmin	Sunucu yöneticisi hesaplar her şeyi yapabilir
Veritabanı rolleri	IS_ROLEMEMBER: db_owner, db_datawriter, db_ddladmin, db_securityadmin	Yazma/DDL yetkisi veren standart roller
Efektif izinler	sys.fn_my_permissions(NULL, 'DATABASE') içinde INSERT, UPDATE, DELETE, ALTER, CREATE TABLE, EXECUTE, CONTROL aranır	Rol üyeliği olmadan doğrudan GRANT ile verilmiş yazma izinlerini yalnızca bu kontrol yakalar

Doğrulama başarısızsa sunucu hiçbir sorgu aracı açmaz; hangi yetkilerin sorun olduğunu listeleyen, yol gösterici bir hata döner (yalnızca verify_connection aracı kalır).

Katman 2 — Sorgu seviyesinde savunma derinliği. Kullanıcı salt-okunur olsa BİLE her sorgu şu filtrelerden geçer:

1. Tek statement: Noktalı virgülle ayrılmış çoklu statement reddedilir. String literal içindeki ; yanlış pozitif üretmez — düz regex değil, string/yorum/köşeli parantez bilinçli bir tokenizer kullanılır.
2. Yalnızca SELECT: Statement SELECT veya WITH ... SELECT (CTE) ile başlamalıdır.
3. Kara liste (kelime sınırı duyarlı, büyük/küçük harf duyarsız): INSERT, UPDATE, DELETE, MERGE, DROP, CREATE, ALTER, TRUNCATE, GRANT, REVOKE, DENY, EXEC, EXECUTE, sp_*, xp_*, OPENROWSET, OPENQUERY, OPENDATASOURCE, BULK, BACKUP, RESTORE, SHUTDOWN, KILL, RECONFIGURE, WAITFOR, INTO (SELECT ... INTO tablo yaratır — reddedilir).
4. Tablo beyaz listesi (opsiyonel): ALLOWED_TABLES tanımlıysa FROM/JOIN sonrası geçen her tablo listede olmalıdır (şema önekli adlar desteklenir; CTE adları muaftır).
5. Zaman aşımı ve satır limiti: Her sorguya QUERY_TIMEOUT_MS uygulanır; sonuçlar sürücü seviyesinde stream edilip MAX_ROWS'ta kesilir ve truncated: true bildirilir (sorgunuza TOP enjekte edilmez).
6. Reddedilen her sorguda hangi kuralın tetiklendiği açıkça söylenir.

Ek güvenlik varsayılanları: bağlantı havuzu tek ve paylaşımlıdır, kimlik bilgileri asla loglanmaz ve hata mesajlarından temizlenir, TLS varsayılan olarak açıktır.

Kurulum

# npx ile (önerilen) — kurulum gerektirmez, her çalıştırmada güncel sürümü kullanır
npx -y @esasiyun17/mssql-mcp

# veya kalıcı kurulum
npm install -g @esasiyun17/mssql-mcp

Kaynak koddan kurulum (air-gap / kapalı ağ ortamları)

İnternet erişimi olmayan ortamlarda npx çalışmaz. Repoyu klonlayıp (veya arşiv olarak taşıyıp) yerinde derleyin:

git clone https://github.com/esasiyun17/MSSQL-MCP.git
cd MSSQL-MCP
npm install
npm run build

Ardından MCP yapılandırmasında npx yerine doğrudan node + tam yol kullanın:

{
  "mcpServers": {
    "mssql": {
      "command": "node",
      "args": ["/tam/yol/MSSQL-MCP/dist/index.js"],
      "env": { "MSSQL_HOST": "...", "MSSQL_USER": "...", "MSSQL_PASSWORD": "...", "MSSQL_DATABASE": "..." }
    }
  }
}

İpucu: npm install adımı için bağımlılıkları internet erişimli bir makinede indirip node_modules ile birlikte taşıyabilir veya npm pack çıktısını kullanabilirsiniz.

Salt-okunur kullanıcı oluşturma

Sunucu, yazma yetkisi olan kullanıcılarla çalışmayı reddeder. Hazır script ile salt-okunur kullanıcı oluşturun:

-- scripts/create-readonly-user.sql dosyasını açın,
-- YOUR_LOGIN_NAME / YOUR_STRONG_PASSWORD / YOUR_DATABASE değerlerini değiştirip
-- sysadmin bir hesapla çalıştırın. Özet:
CREATE LOGIN [mcp_reader] WITH PASSWORD = 'YOUR_STRONG_PASSWORD';
USE [YOUR_DATABASE];
CREATE USER [mcp_reader] FOR LOGIN [mcp_reader];
ALTER ROLE [db_datareader] ADD MEMBER [mcp_reader];

Claude Desktop / Claude Code yapılandırması

claude_desktop_config.json (Claude Desktop) veya .mcp.json (Claude Code):

{
  "mcpServers": {
    "mssql": {
      "command": "npx",
      "args": ["-y", "@esasiyun17/mssql-mcp"],
      "env": {
        "MSSQL_HOST": "192.168.1.10",
        "MSSQL_PORT": "1433",
        "MSSQL_USER": "mcp_reader",
        "MSSQL_PASSWORD": "YOUR_PASSWORD",
        "MSSQL_DATABASE": "ErpDb",
        "MSSQL_ENCRYPT": "true",
        "MSSQL_TRUST_CERT": "false",
        "MAX_ROWS": "1000",
        "ALLOWED_TABLES": "dbo.Customers,dbo.Orders,dbo.OrderLines"
      }
    }
  }
}

Claude Code CLI ile:

claude mcp add mssql -e MSSQL_HOST=192.168.1.10 -e MSSQL_USER=mcp_reader \
  -e MSSQL_PASSWORD=YOUR_PASSWORD -e MSSQL_DATABASE=ErpDb -- npx -y @esasiyun17/mssql-mcp

Ortam değişkenleri

Değişken	Zorunlu	Varsayılan	Açıklama
MSSQL_HOST	✅	—	Sunucu IP veya hostname
MSSQL_PORT		1433	TCP port
MSSQL_USER	✅	—	SQL auth kullanıcı adı (salt-okunur olmalı)
MSSQL_PASSWORD	✅	—	Parola (asla loglanmaz)
MSSQL_DATABASE	✅	—	Veritabanı adı
MSSQL_ENCRYPT		true	TLS şifreleme
MSSQL_TRUST_CERT		false	Self-signed sertifika kabulü
QUERY_TIMEOUT_MS		30000	Sorgu zaman aşımı (ms)
MAX_ROWS		1000	Satır limiti; aşımda sonuç kesilir ve bildirilir
ALLOWED_TABLES		(boş = tümü)	Virgülle ayrılmış tablo beyaz listesi, örn. dbo.Customers,dbo.Orders
LOG_FILE		(kapalı)	JSON-satırı denetim logu dosya yolu

Araçlar

Araç	Açıklama
verify_connection	Bağlantı durumu + salt-okunurluk doğrulama raporu (hangi kontroller geçti/kaldı)
list_tables	şema.tablo listesi + yaklaşık satır sayıları (sys.partitions üzerinden, COUNT(*) çalıştırılmaz)
describe_table(table)	Kolonlar, tipler, null'luk, PK/FK, index listesi
sample_rows(table, count)	İlk N satır (varsayılan 5, en fazla 50)
run_query(sql)	Tüm filtrelerden geçen tek bir SELECT'i çalıştırır

Örnek kullanım (Claude'a doğal dille):

"Veritabanındaki tabloları listele" → list_tables "Orders tablosunun yapısını göster" → describe_table("dbo.Orders") "Geçen ayın en çok satan 5 ürünü?" → run_query("SELECT TOP 5 ...")

run_query çıktısı: columns, rows, rowCount, truncated, durationMs.

Denetim logu

LOG_FILE tanımlıysa her araç çağrısı bir JSON satırı olarak yazılır: zaman damgası, araç adı, sorgu metni, süre (ms), satır sayısı, hata. Kimlik bilgileri asla loglanmaz.

Yol haritası

• Windows Authentication (v1 yalnızca SQL auth destekler — kapsam bilinçli dar tutuldu)

Katkı

PR ve issue'lara açığız! Özellikle: yeni guard senaryoları için test, farklı SQL Server sürümleriyle uyumluluk raporları, dokümantasyon iyileştirmeleri. Tek kırmızı çizgi: yazma yeteneği ekleyen hiçbir katkı kabul edilmez — salt-okunurluk bu projenin kimliğidir. Güvenlik açıkları için SECURITY.md.

---

🇬🇧 English

What is this?

MSSQL-MCP is an MCP server designed to connect LLMs (like Claude) to enterprise Microsoft SQL Server databases safely. The LLM translates natural-language questions into SQL; MSSQL-MCP runs that SQL only after it passes layered security filters that guarantee it is read-only.

Why? — The risks of wiring an LLM straight into your database

Giving an LLM database access is powerful but dangerous:

• The LLM can produce destructive queries (DELETE, UPDATE, DROP) by accident — or deliberately, via prompt injection.
• The user you assumed was read-only may have write access through a forgotten GRANT.
• Even an unbounded SELECT can pull millions of rows and choke the server.
• Escape hatches like xp_cmdshell and OPENROWSET reach far beyond the database.

Security philosophy: read-only verification + defense in depth

MSSQL-MCP never trusts a single layer:

Layer 1 — Active read-only verification at startup. When the server starts, the connecting user must actively prove it is read-only. ALL three independent checks must pass:

Check	How	Why
Server roles	IS_SRVROLEMEMBER: sysadmin, serveradmin, dbcreator, securityadmin	Server-admin accounts can do anything
Database roles	IS_ROLEMEMBER: db_owner, db_datawriter, db_ddladmin, db_securityadmin	The standard roles that grant write/DDL
Effective permissions	sys.fn_my_permissions(NULL, 'DATABASE') scanned for INSERT, UPDATE, DELETE, ALTER, CREATE TABLE, EXECUTE, CONTROL	Only this catches write permissions GRANTed directly, outside any role

If verification fails the server exposes no query tools at all; it returns an actionable error listing exactly which privileges are the problem (only verify_connection remains available).

Layer 2 — Query-level defense in depth. EVEN IF the user is read-only, every query passes these filters:

1. Single statement only: multiple semicolon-separated statements are rejected. A ; inside a string literal is not a false positive — a tokenizer aware of strings, comments and bracketed identifiers is used, not a plain regex.
2. SELECT only: the statement must start with SELECT or WITH ... SELECT (CTE).
3. Keyword blacklist (word-boundary aware, case-insensitive): INSERT, UPDATE, DELETE, MERGE, DROP, CREATE, ALTER, TRUNCATE, GRANT, REVOKE, DENY, EXEC, EXECUTE, sp_*, xp_*, OPENROWSET, OPENQUERY, OPENDATASOURCE, BULK, BACKUP, RESTORE, SHUTDOWN, KILL, RECONFIGURE, WAITFOR, INTO (SELECT ... INTO creates a table — rejected).
4. Optional table allowlist: when ALLOWED_TABLES is set, every table appearing after FROM/JOIN must be on the list (schema-qualified names supported; CTE names are exempt).
5. Timeout & row cap: QUERY_TIMEOUT_MS applies to every query; results are streamed at the driver level and cut off at MAX_ROWS with truncated: true reported (no TOP is injected into your SQL).
6. Every rejected query states exactly which rule fired.

Additional safe defaults: one shared connection pool, credentials are never logged and are scrubbed from error messages, TLS is on by default.

Installation

# via npx (recommended) — no install step, always runs the latest version
npx -y @esasiyun17/mssql-mcp

# or install globally
npm install -g @esasiyun17/mssql-mcp

Installing from source (air-gapped / offline environments)

npx won't work without internet access. Clone the repo (or carry it over as an archive) and build in place:

git clone https://github.com/esasiyun17/MSSQL-MCP.git
cd MSSQL-MCP
npm install
npm run build

Then point your MCP configuration at node + the absolute path instead of npx:

{
  "mcpServers": {
    "mssql": {
      "command": "node",
      "args": ["/absolute/path/MSSQL-MCP/dist/index.js"],
      "env": { "MSSQL_HOST": "...", "MSSQL_USER": "...", "MSSQL_PASSWORD": "...", "MSSQL_DATABASE": "..." }
    }
  }
}

Tip: for the npm install step you can download dependencies on a machine with internet access and carry the node_modules folder over, or use the output of npm pack.

Creating a read-only user

The server refuses to run with users that hold write privileges. Use the bundled script to create a read-only user:

-- Open scripts/create-readonly-user.sql, replace
-- YOUR_LOGIN_NAME / YOUR_STRONG_PASSWORD / YOUR_DATABASE and run as sysadmin. Summary:
CREATE LOGIN [mcp_reader] WITH PASSWORD = 'YOUR_STRONG_PASSWORD';
USE [YOUR_DATABASE];
CREATE USER [mcp_reader] FOR LOGIN [mcp_reader];
ALTER ROLE [db_datareader] ADD MEMBER [mcp_reader];

Claude Desktop / Claude Code configuration

claude_desktop_config.json (Claude Desktop) or .mcp.json (Claude Code):

{
  "mcpServers": {
    "mssql": {
      "command": "npx",
      "args": ["-y", "@esasiyun17/mssql-mcp"],
      "env": {
        "MSSQL_HOST": "192.168.1.10",
        "MSSQL_PORT": "1433",
        "MSSQL_USER": "mcp_reader",
        "MSSQL_PASSWORD": "YOUR_PASSWORD",
        "MSSQL_DATABASE": "ErpDb",
        "MSSQL_ENCRYPT": "true",
        "MSSQL_TRUST_CERT": "false",
        "MAX_ROWS": "1000",
        "ALLOWED_TABLES": "dbo.Customers,dbo.Orders,dbo.OrderLines"
      }
    }
  }
}

With the Claude Code CLI:

claude mcp add mssql -e MSSQL_HOST=192.168.1.10 -e MSSQL_USER=mcp_reader \
  -e MSSQL_PASSWORD=YOUR_PASSWORD -e MSSQL_DATABASE=ErpDb -- npx -y @esasiyun17/mssql-mcp

Environment variables

Variable	Required	Default	Description
MSSQL_HOST	✅	—	Server IP or hostname
MSSQL_PORT		1433	TCP port
MSSQL_USER	✅	—	SQL auth user name (must be read-only)
MSSQL_PASSWORD	✅	—	Password (never logged)
MSSQL_DATABASE	✅	—	Database name
MSSQL_ENCRYPT		true	TLS encryption
MSSQL_TRUST_CERT		false	Accept self-signed certificates
QUERY_TIMEOUT_MS		30000	Per-query timeout (ms)
MAX_ROWS		1000	Row cap; results are truncated and flagged
ALLOWED_TABLES		(empty = all)	Comma-separated table allowlist, e.g. dbo.Customers,dbo.Orders
LOG_FILE		(off)	Path for the JSON-lines audit log

Tools

Tool	Description
verify_connection	Connection status + read-only verification report (which checks passed/failed)
list_tables	schema.table list + approximate row counts (via sys.partitions, no COUNT(*))
describe_table(table)	Columns, types, nullability, PK/FK, index list
sample_rows(table, count)	First N rows (default 5, max 50)
run_query(sql)	Runs a single SELECT after all defense filters

Example usage (natural language, via Claude):

"List the tables in the database" → list_tables "Show me the structure of Orders" → describe_table("dbo.Orders") "Top 5 products by revenue last month?" → run_query("SELECT TOP 5 ...")

run_query output: columns, rows, rowCount, truncated, durationMs.

Audit log

When LOG_FILE is set, every tool call is appended as one JSON line: timestamp, tool name, query text, duration (ms), row count, error. Credentials are never logged.

Roadmap

• Windows Authentication (v1 supports SQL auth only — scope kept deliberately narrow)

Contributing

PRs and issues welcome! Especially: tests for new guard scenarios, compatibility reports for different SQL Server versions, documentation improvements. One hard line: no contribution that adds write capability will be accepted — read-only is this project's identity. For vulnerabilities see SECURITY.md.

License / Lisans

MIT © esasiyun17