Memungkinkan LLM agent untuk melakukan diagnostik SQL Server secara read-only menggunakan Query Store, execution plans, dan wait statistics.
Juga dikenal sebagai deepeshd87/mcp-sql-querystore
- Stars
- 1
- Tools
- 6
- Unduhan, 30 hari
- 124
- Versi terbaru
- 0.1.1
- Commit terakhir
- 3 Okt 2026
- Lisensi
- MIT
Apa itu sql-querystore MCP?
Memungkinkan LLM agent untuk melakukan diagnostik SQL Server secara read-only menggunakan Query Store, execution plans, dan wait statistics. Server ini menyediakan 6 tool, seperti get_regressed_queries, get_query_execution_plan, analyze_parameter_sniffing.
Ringkasan dibuat dari README proyek
Tentang sql-querystore MCP server
Database administrator dan developer dapat mendiagnosis masalah performa SQL Server secara langsung melalui client AI menggunakan MCP server read-only ini. Server ini terhubung ke instance SQL Server Anda untuk mengekspos data diagnostik dari Query Store, Dynamic Management Views, dan execution plans. Dengan memberikan akses ke metrik spesifik ini kepada LLM, Anda dapat melakukan triage performa yang kompleks tanpa harus menulis query diagnostik secara manual.
Server ini beroperasi sebagai stdio server dan memerlukan instalasi ODBC Driver 18 for SQL Server pada host. Keamanan dijaga melalui SQL login khusus dengan izin VIEW DATABASE STATE, yang memastikan agent tidak dapat mengakses tabel user atau mengubah data. Anda dapat mengonfigurasi konektivitas menggunakan environment variables, termasuk opsi untuk integrated authentication atau file password agar kredensial tetap aman dari file konfigurasi Anda.
Tool spesifik tersedia untuk analisis mendalam, seperti get_regressed_queries untuk mengidentifikasi penurunan performa, analyze_parameter_sniffing untuk menemukan plan yang tidak stabil, dan get_missing_index_impact untuk memprioritaskan kebutuhan indexing. Tool sweep_regressions bahkan memungkinkan pemindaian seluruh database yang mengaktifkan Query Store secara sekaligus untuk menemukan masalah performa yang paling parah.
Apa yang bisa Anda lakukan dengannya
- 1Identifikasi regressed queriesMinta AI untuk menemukan query yang menjadi jauh lebih lambat dibandingkan dengan baseline sebelumnya.
- 2Analisis execution plansMinta ringkasan dari execution plan query tertentu untuk memeriksa peringatan atau missing indexes.
- 3Diagnosis wait statisticsTentukan apakah kelambatan database disebabkan oleh bottleneck CPU, memory, atau IO.
- 4Deteksi parameter sniffingTemukan query yang mengalami masalah execution plan tidak stabil akibat parameter sniffing.
- 5Lakukan pemindaian multi-databaseInstruksikan agent untuk memindai setiap database online guna menemukan regresi performa yang paling parah.
Ditulis berdasarkan README proyek. Setiap use case diperiksa terhadap kutipan dari README tersebut.
Cara menginstal sql-querystore MCP
Format diverifikasi 10 Nov 2026Tambahkan ke CursorTambahkan ke GooseInstal sql-querystore MCP di Claude Code
$ claude mcp add mcp-sql-querystore -- uvx mcp-sql-querystoreInstal sql-querystore MCP di Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-sql-querystore": {
"command": "uvx",
"args": [
"mcp-sql-querystore"
]
}
}
}Instal sql-querystore MCP di VS Code
.vscode/mcp.json
{
"servers": {
"mcp-sql-querystore": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-sql-querystore"
]
}
}
}Instal sql-querystore MCP di VS Code CLI
$ code --add-mcp '{"name":"mcp-sql-querystore","type":"stdio","command":"uvx","args":["mcp-sql-querystore"]}'Instal sql-querystore MCP di Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-sql-querystore": {
"command": "uvx",
"args": [
"mcp-sql-querystore"
]
}
}
}Instal sql-querystore MCP di Codex
$ codex mcp add mcp-sql-querystore -- uvx mcp-sql-querystoreInstal sql-querystore MCP di Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-sql-querystore] command = "uvx" args = ["mcp-sql-querystore"]
Instal sql-querystore MCP di Gemini CLI
$ gemini mcp add -s user mcp-sql-querystore uvx -- mcp-sql-querystoreInstal sql-querystore MCP di Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-sql-querystore": {
"command": "uvx",
"args": [
"mcp-sql-querystore"
]
}
}
}Tool sql-querystore MCP 6
Terdeteksi dari READMEget_regressed_queriesget_query_execution_plananalyze_parameter_sniffingget_missing_index_impactget_wait_statssweep_regressions
| get_regressed_queries | — | |
| get_query_execution_plan | — | |
| analyze_parameter_sniffing | — | |
| get_missing_index_impact | — | |
| get_wait_stats | — | |
| sweep_regressions | — |
Pengecekan otomatis
Berjalan 14 Nov 2026Laporan lengkap →Lolos checks otomatis kami. Ini bukan audit keamanan: baca kodenya dan berikan server akses paling terbatas yang dibutuhkannya. Cara kerja checks
- Source repository terhubung dan dapat dijangkaudeepeshd87/mcp-sql-querystore is public and reachablegithub.com/deepeshd87/mcp-sql-querystore ↗Lolos
- Nama paket mencantumkan repositori ini sebagai sumbernyamcp-sql-querystore names deepeshd87/mcp-sql-querystore as sourcepypi.org/project/mcp-sql-querystore/ ↗Lolos
- Provenance build (atestasi Sigstore)No build attestation published for this releaseTidak diperiksa
- Lisensi open source (OSI)MITspdx.org/licenses/MIT.html ↗Lolos
- Ada commit atau release dalam satu tahun terakhirLast commit or release 2026-10-03github.com/deepeshd87/mcp-sql-querystore ↗Lolos
- OpenSSF ScorecardTidak diperiksa
- Nama package tidak mirip dengan package populerNo popular package one edit away from mcp-sql-querystoreLolos
- Tidak ada advisory kritis pada paket atau dependensinya31 resolved dependencies checked; no critical advisoryosv.dev ↗Lolos
- Tidak ada instruksi tersembunyi untuk model6 tool descriptions and the README read; no override phrases, credential paths or hidden charactersLolos
- Tools yang bersifat destruktif telah diberi labelNo tool named like delete, drop or execLolos
- Endpoint remote merespons handshake MCPTidak diperiksa
README
Lihat di GitHubmcp-name: io.github.deepeshd87/mcp-sql-querystore
mcp-sql-querystore
Read-only MCP server exposing SQL Server Query Store diagnostics to LLM agents.
Six read-only diagnostic tools over Query Store, DMVs, and execution plans. The tools have been validated against a live SQL Server instance and are covered by a unit + integration test suite. Still validate against a non-prod instance of your own before pointing it at production, especially on SQL Server versions other than those noted under caveats.
Quickstart
-
Provision a read-only login. Run
provisioning/create_readonly_login.sqlagainst your instance (edit names first). This login's permissions are the read-only guarantee — see the security model below. -
Install.
pip install -e .in a virtual environment. ODBC Driver 18 for SQL Server must be installed on the host. -
Store the password outside the repo. Put it in a plain-text file somewhere the repo can't reach (not under the project folder):
# Windows PowerShell, UTF-8, password only, no quotes/newline New-Item -ItemType Directory -Force C:\Users\you\secrets | Out-Null Set-Content -NoNewline -Encoding utf8 C:\Users\you\secrets\mcp_sql.pwd 'your-password'Or skip the password entirely with integrated auth (
MCP_SQL_TRUSTED=yes) — preferred for CJIS/PCI. See Secret handling below for all options. -
Configure your MCP client. Copy the
sql-querystoreblock fromclaude_desktop_config.example.jsoninto your real Claude Desktop config (Windows:%APPDATA%\Claude\claude_desktop_config.json), then replace the placeholder paths, server name, andMCP_SQL_PWD_FILE. SetMCP_SQL_TRUST_CERT=yesonly for a self-signed/local cert; leave itnoagainst instances with proper certificates. -
Restart your MCP client and confirm the server shows as running.
Never commit your real config or your password file. .gitignore already
excludes *.pwd, .env, and claude_desktop_config.json.
Security model (read this first)
The read-only guarantee comes from the SQL login's permissions, not from any code in this repo:
- Provision a dedicated login with
VIEW DATABASE STATE(andVIEW SERVER STATEonly if you use server-scoped DMVs) and nothing else — nodb_datareader, noSELECTon user tables. Seeprovisioning/create_readonly_login.sql. - The keyword screen in
db.pyand the fixed SELECT-only query text are defense-in-depth, not the primary control. ApplicationIntent=ReadOnlyin the connection string only routes to a readable secondary in an availability group. On a standalone instance it does not make the session read-only. Do not rely on it for safety.- Credentials never belong in code. The simplest setup uses the
MCP_SQL_CONNECTION_STRINGenv var, but for CJIS/PCI environments prefer integrated auth or a file/secret-store-sourced password — see the Secret handling section below. - Every query is recorded via the audit logger — see Audit logging below. In a regulated environment, route that logger to a durable file or SIEM.
Setup
ODBC Driver 18 for SQL Server must be installed on the host. Install the package, then configure the connection via environment variables (see Secret handling for all options). The recommended form keeps the password in a file, not inline:
pip install -e .
# PowerShell — connection assembled from parts, password read from a file
$env:MCP_SQL_SERVER = "yourhost\INSTANCE"
$env:MCP_SQL_DATABASE = "master"
$env:MCP_SQL_UID = "mcp_readonly"
$env:MCP_SQL_PWD_FILE = "C:\path\to\your\secret.pwd"
$env:MCP_SQL_TRUST_CERT = "no" # "yes" only for a self-signed/local cert
python -m mcp_sql_querystore.server
Or use integrated auth with no stored password at all (MCP_SQL_TRUSTED=yes).
A full MCP_SQL_CONNECTION_STRING is also accepted for simple cases — see
Secret handling.
Register it with your MCP client (e.g. Claude Desktop) as an stdio server
invoking python -m mcp_sql_querystore.server; see
claude_desktop_config.example.json.
Tools
All tools are read-only and take a database_name (except sweep_regressions,
which can sweep all databases). Each returns JSON, or a structured error dict on
failure rather than raising.
- get_regressed_queries — compares a recent window against an earlier
baseline window per query and flags those worse by at least
regression_threshold. A real baseline-vs-recent comparison, not a top-CPU list. - get_query_execution_plan — returns compiled plans for a
query_idwith a compact JSON summary (missing indexes, warnings incl. implicit conversions, key lookups) and optional raw XML. - analyze_parameter_sniffing — finds queries with multiple compiled plans and ranks them by the ratio of slowest to fastest plan mean duration — the classic parameter-sniffing signature.
- get_missing_index_impact — scans recent plans containing missing-index recommendations, parses the impact score from the plan XML, and aggregates duplicate recommendations across queries, ranked by impact then recurrence.
- get_wait_stats — aggregates query wait time by wait category over a window, showing why queries are slow (CPU, blocking/locks, IO, memory) rather than which. De-duplicates flushed vs in-memory rows per Microsoft guidance.
- sweep_regressions — runs regression detection across all Query Store-enabled
online databases (or an explicit
database_nameslist) and returns the worst per database, ranked. One failing database does not abort the sweep; its error is collected and reported.
Example prompts
Once the server is connected to your MCP client, you drive the tools in plain
language. Name the target database in the prompt (except sweep_regressions,
which can scan all of them). Replace YourDB with your database name.
Wait stats — why queries are slow
- "What are the top wait categories in YourDB over the last week?"
- "Is YourDB waiting on CPU, memory, or IO?"
- "Show me wait stats for YourDB over the last 24 hours."
Execution plans
- "Get the execution plan for query_id 10 in YourDB and summarize it."
- "Does query_id 13 in YourDB have missing index recommendations?"
- "Are there implicit conversion warnings in query 12's plan in YourDB?"
Regression analysis
- "Check YourDB for CPU regressions over the last 24 hours."
- "Which queries in YourDB regressed by more than 30%?"
- "Find duration regressions in YourDB, ignoring anything with fewer than 10 executions."
Parameter sniffing
- "Check YourDB for parameter sniffing."
- "Which queries in YourDB have unstable plans?"
Missing indexes
- "What missing indexes does YourDB need most?"
- "Show me the top 10 index recommendations for YourDB by impact."
Multi-database sweep (no database name needed)
- "Sweep all my databases for CPU regressions."
- "Which database has the worst regressions this week?"
Combined — chaining tools in one turn
- "Find the biggest CPU regression in YourDB, pull its plan, and tell me why it might have regressed."
- "YourDB feels slow — diagnose it." (wait stats → regressions → plans)
- "Full performance triage of YourDB: wait stats, top regressions, and missing indexes."
Known caveats / TODO
- Version differences. Query Store column names assume SQL Server 2019+/2022 and Azure SQL MI. Verify against 2016/2017 if you target those.
- Regression semantics. Current logic uses execution-weighted averages. You
may prefer percentile-based comparison (Query Store doesn't store percentiles
directly, so that needs
*_stdevcolumns and assumptions). - Not time-windowed:
analyze_parameter_sniffingaggregates across all Query Store history; on busy databases consider adding arecent_hoursfilter like the other tools have. - Remaining hardening: connection retry with backoff, and version-aware column handling for mixed 2016/2017/2019/2022 fleets.
Secret handling
The connection string is resolved in this order, so the password need not sit in plaintext config:
MCP_SQL_CONNECTION_STRING— the full string (simplest; back-compat).MCP_SQL_CONNECTION_STRING_FILE— path to a file holding the full string (Docker/K8s secret-mount style).- Assembled from parts:
MCP_SQL_SERVER(+MCP_SQL_DATABASE,MCP_SQL_DRIVER,MCP_SQL_ENCRYPT,MCP_SQL_TRUST_CERT,MCP_SQL_EXTRA). Auth is either:- Integrated (preferred for CJIS/PCI — no password stored):
MCP_SQL_TRUSTED=yes. - SQL auth:
MCP_SQL_UIDplus the password fromMCP_SQL_PWD_FILE(a vault-mounted file),MCP_SQL_PWD_ENV(name of another env var), orMCP_SQL_PWD(direct; least preferred).
- Integrated (preferred for CJIS/PCI — no password stored):
Timeouts: MCP_SQL_CONNECT_TIMEOUT (default 10s) and MCP_SQL_QUERY_TIMEOUT
(default 30s, 0 disables).
Audit logging
Every query attempt is logged via the mcp_sql_querystore.audit logger: tool,
database, a 12-char hash of the SQL (not the text), row count, elapsed ms, and
outcome. Connection strings, SQL text, and parameter values are never logged.
Configure a handler for that logger to route the audit trail to a file or SIEM.
Testing
Unit tests (no database, safe in CI):
pip install -e ".[test]"
pytest
Integration tests (real instance, opt-in):
# set a working connection (any form above), then:
$env:MCP_SQL_TEST_DATABASE = "RAG"
$env:MCP_SQL_RUN_INTEGRATION = "1"
pytest tests/test_integration.py -v
Pertanyaan tentang sql-querystore MCP
Bagaimana cara menambahkan sql-querystore MCP ke Claude Code?
Jalankan claude mcp add mcp-sql-querystore -- uvx mcp-sql-querystore di terminal Anda. Tambahkan --scope user agar tersedia di semua proyek.
Bagaimana cara menambahkan sql-querystore MCP ke Cursor?
Buka ~/.cursor/mcp.json dan tambahkan server di bawah mcpServers, menggunakan config Cursor yang ditunjukkan di bagian instalasi di atas.
Tool apa yang disediakan sql-querystore MCP?
Server ini menyediakan 6 tool, termasuk get_regressed_queries, get_query_execution_plan, analyze_parameter_sniffing, get_missing_index_impact, get_wait_stats.
Apakah server ini aman digunakan pada database produksi?
Server ini bersifat read-only, namun Anda sebaiknya melakukan validasi terlebih dahulu pada instance non-produksi, terutama pada versi SQL Server selain yang disebutkan dalam catatan peringatan.
Informasi diagnostik apa saja yang dapat diakses oleh AI?
Server menyediakan tool untuk regressed queries, execution plans, analisis parameter sniffing, dampak missing index, dan wait statistics.
Apakah server ini mencatat informasi sensitif seperti teks SQL?
Tidak, audit logger hanya mencatat tool, database, hash dari SQL, jumlah baris, dan elapsed time, tetapi tidak pernah mencatat connection strings, teks SQL, atau nilai parameter.