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:

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

Araçlar

Ö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.

Related MCP server: sql-explorer-mcp

🇬🇧 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:

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

Tools

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