mcp-mssql — Claude için MSSQL MCP Sunucusu

MSSQL’e Model Context Protocol (MCP) üzerinden güvenli bağlanan, STDIO modunda çalışan bir sunucudur.
Claude Desktop (ve MCP uyumlu diğer istemciler) tarafından harici bir tool olarak başlatılır.

NL→SQL: doğal dilde sor — Claude şemayı (discover_schema) kullanarak SQL üretir ve run_sql_safe ile çalıştırır.

---

✨ Özellikler

• connect_db — Ortam değişkenleriyle MSSQL bağlantısını dener (sağlık kontrolü).
• discover_schema — INFORMATION_SCHEMA tabanlı tablo/kolon keşfi; basit heuristiklerle date_cols, measures, dims etiketleri üretir.
• run_sql_safe — Tek SELECT ifadesini çalıştırır. DDL/DML ve çoklu ifadeler engellenir. Otomatik TOP 5000 enjekte edilir (sorguda varsa dokunmaz).

🛡️ Guardrails: DROP/UPDATE/INSERT/MERGE/EXEC vb. yasak; ;, --, /* */ gibi çoklu ifade/yorum kalıpları reddedilir; 15 sn timeout.

---

🧰 Gereksinimler

• Node.js 18+ (öneri: 20+)
• MSSQL (lokal / Docker / uzak / Azure SQL)

---

🔧 Kurulum

git clone https://github.com/ismailcankaratas/mcp-mssql.git
cd mcp-mssql
npm install

.env oluştur (repo kökünde):

MSSQL_HOST=localhost
MSSQL_PORT=1433
MSSQL_DB=YourDatabase
MSSQL_USER=readonly_login
MSSQL_PWD=ReadOnly!123

Geliştirmede encrypt=true ve trustServerCertificate=true varsayılan. Üretimde geçerli sertifika ile encrypt=true kullanın.

---

▶️ Çalıştırma

Geliştirme (TSX ile)

npm run dev

Build & Start

npm run build
npm start

---

🧪 Hızlı Bağlantı Testi

npx tsx src/test_local.ts

Beklenen:

OK: [ { current_db: "...", version: "Microsoft SQL Server 2022 ..." } ]

---

🖥️ Claude Desktop Entegrasyonu

Config dosyası (claude_desktop_config.json) örneği:

{
  "mcpServers": {
    "mssql": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/dist/server.js"],
      "env": {
        "MSSQL_HOST": "localhost",
        "MSSQL_PORT": "1433",
        "MSSQL_DB": "YourDatabase",
        "MSSQL_USER": "readonly_login",
        "MSSQL_PWD": "ReadOnly!123"
      }
    }
  }
}

Geliştirmede TS kaynakla koşmak istersen Command: "tsx", Args: ["src/server.ts"] kullanabilirsin.

---

🧭 Claude içinde kullanım örnekleri

• Bağlantı testi

  tool: connect_db {}
  

• Şemayı keşfet

  tool: discover_schema {}
  

• Güvenli sorgu çalıştır

  tool: run_sql_safe {"sql":"SELECT TOP 5 name FROM sys.databases ORDER BY name"}
  

NL→SQL: doğal dilde sor — Claude şemayı (discover_schema) kullanarak SQL üretir ve run_sql_safe ile çalıştırır.

---

🔒 Güvenlik Notları

• Üretimde salt-okuma kullanıcı (db_datareader) kullanın.
• run_sql_safe yalnızca tek bir SELECT’e izin verir; DDL/DML ve çoklu ifadeler reddedilir.
• Maksimum satır sayısı için TOP otomatik enjekte edilir (varsayılan: 5000).
• Sorgu süresi varsayılan 15s timeout ile sınırlıdır.
• .env ve gizli bilgileri asla versiyona eklemeyin.

---

🩺 Sorun Giderme

• ENOTFOUND / ECONNREFUSED / ETIMEDOUT → Host/port doğru mu? Docker portu açık mı?
• ELOGIN → Kullanıcı/parola doğru mu? DB’de db_datareader yetkisi var mı?
• TLS uyarısı (SNI) → IP yerine MSSQL_HOST=localhost kullanın veya sertifika tanımlayın.
• discover_schema boş → DB’de tablo yok ya da kullanıcı INFORMATION_SCHEMA’ya erişemiyor.

---

📂 Proje Yapısı

src/
  db.ts         # MSSQL bağlantısı ve query helper
  schema.ts     # INFORMATION_SCHEMA keşfi + heuristik etiketler
  server.ts     # MCP server (connect_db, discover_schema, run_sql_safe)
  test_local.ts # MSSQL bağlantı smoke testi

---

📄 Lisans

MIT