Memberikan pengetahuan schema SQL read-only dan kemampuan query yang aman dari PII bagi coding agent untuk SQL Server, MySQL, dan MariaDB.
Juga dikenal sebagai proprock/sql-mini-mcp, sql-mini-mcp
- Stars
- 0
- Tools
- —
- Unduhan, 30 hari
- 154
- Versi terbaru
- 1.1.0
- Commit terakhir
- 14 Nov 2026
- Lisensi
- MIT
Apa itu sql-safe MCP?
sql-safe adalah MCP server. Memberikan pengetahuan schema SQL read-only dan kemampuan query yang aman dari PII bagi coding agent untuk SQL Server, MySQL, dan MariaDB.
Ringkasan dibuat dari README proyek
Tentang sql-safe MCP server
SQL Mini MCP menyediakan cara aman bagi coding agent untuk berinteraksi dengan database SQL Server, MySQL, dan MariaDB. Tool ini dirancang untuk developer yang perlu memberikan pengetahuan schema kepada model AI tanpa risiko modifikasi data atau mengekspos informasi sensitif. Server ini beroperasi sebagai interface read-only, memastikan tidak ada tool yang dapat menulis atau mengubah data pada database yang terhubung.
User dapat mengonfigurasi berbagai level akses, seperti metadata-only atau kemampuan query penuh. Saat menggunakan setting all_pii_safe, server melindungi data pribadi dengan mengganti nilai plaintext menjadi token terautentikasi. Hal ini memungkinkan agent untuk melakukan filter atau menghitung record menggunakan token tanpa pernah melihat konten sensitif yang sebenarnya. Server ini digunakan secara lokal via stdio dengan client seperti Claude Desktop atau Claude Code, dan memerlukan file konfigurasi YAML serta environment variables untuk connection strings.
Keamanan menjadi fokus utama, dengan fitur seperti verifikasi TLS untuk alias sensitif dan allowlist untuk validasi SQL. Sistem ini mencegah eksposur kredensial di dalam log dan memastikan bahwa error tidak membocorkan detail koneksi atau data baris.
Apa yang bisa Anda lakukan dengannya
- 1Eksplorasi struktur databaseAgent dapat mengambil informasi mengenai tabel, kolom, key, dan index untuk memahami schema database.
- 2Query data dengan privasiDeveloper dapat mengizinkan agent untuk menjalankan query SELECT di mana kolom sensitif telah dimasker menggunakan token terautentikasi.
- 3Validasi aturan perlindungan PIIDeveloper dapat memeriksa konfigurasi mereka untuk memastikan semua kolom sensitif telah tercakup dengan benar oleh aturan perlindungan.
Ditulis berdasarkan README proyek. Setiap use case diperiksa terhadap kutipan dari README tersebut.
Cara menginstal sql-safe MCP
Format diverifikasi 10 Nov 2026Tambahkan ke CursorTambahkan ke GooseInstal sql-safe MCP di Claude Code
$ claude mcp add sql-mini-mcp -- uvx sql-mini-mcpInstal sql-safe MCP di Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"sql-mini-mcp": {
"command": "uvx",
"args": [
"sql-mini-mcp"
]
}
}
}Instal sql-safe MCP di VS Code
.vscode/mcp.json
{
"servers": {
"sql-mini-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"sql-mini-mcp"
]
}
}
}Instal sql-safe MCP di VS Code CLI
$ code --add-mcp '{"name":"sql-mini-mcp","type":"stdio","command":"uvx","args":["sql-mini-mcp"]}'Instal sql-safe MCP di Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"sql-mini-mcp": {
"command": "uvx",
"args": [
"sql-mini-mcp"
]
}
}
}Instal sql-safe MCP di Codex
$ codex mcp add sql-mini-mcp -- uvx sql-mini-mcpInstal sql-safe MCP di Codex config.toml
~/.codex/config.toml
[mcp_servers.sql-mini-mcp] command = "uvx" args = ["sql-mini-mcp"]
Instal sql-safe MCP di Gemini CLI
$ gemini mcp add -s user sql-mini-mcp uvx -- sql-mini-mcpInstal sql-safe MCP di Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"sql-mini-mcp": {
"command": "uvx",
"args": [
"sql-mini-mcp"
]
}
}
}Konfigurasi
REPORTING_SQL_URLSQL_SAFE_MCP_CONFIG
| Nama | Deskripsi | Tipe |
|---|---|---|
| REPORTING_SQL_URL | — | |
| SQL_SAFE_MCP_CONFIG | — |
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 dijangkauproprock/sql-mini-mcp is public and reachablegithub.com/proprock/sql-mini-mcp ↗Lolos
- Nama paket mencantumkan repositori ini sebagai sumbernyaTidak diperiksa
- Provenance build (atestasi Sigstore)Sigstore attestation for sql-mini-mcppypi.org/project/sql-mini-mcp/ ↗Lolos
- Lisensi open source (OSI)MITspdx.org/licenses/MIT.html ↗Lolos
- Ada commit atau release dalam satu tahun terakhirLast commit or release 2026-11-07github.com/proprock/sql-mini-mcp ↗Lolos
- OpenSSF ScorecardTidak diperiksa
- Nama package tidak mirip dengan package populerNo popular package one edit away from sql-mini-mcpLolos
- Tidak ada advisory kritis pada paket atau dependensinya33 resolved dependencies checked; no critical advisoryosv.dev ↗Lolos
- Tidak ada instruksi tersembunyi untuk model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersLolos
- Tools yang bersifat destruktif telah diberi labelTidak diperiksa
- Endpoint remote merespons handshake MCPTidak diperiksa
README
Lihat di GitHubsql-safe-mcp
A PII-safe, read-only MCP server for coding agents working with SQL Server, MySQL and MariaDB: schema knowledge and safe queries without write-capable tools or plaintext exposure of configured PII columns.
Read the data. Protect the identity.
Give a coding agent the schema knowledge it needs to write correct code - servers, databases,
tables, columns, keys, indexes, and stored procedures. On aliases you mark all_pii_safe, it can also
query real rows while configured personal data stays hidden behind authenticated tokens.
PII-safe by default. Read-only by design.
- PII-safe by default - on an
all_pii_safeserver, the columns you configure come back as alias-bound, authenticated tokens (pii:v1:...), never as plaintext. An agent can still project, count, and filter on them with=andINusing tokens it was given, so it can follow a record without reading it. Tokens do not work on another server alias or with another key. - Read-only by construction - seven tools, all annotated read-only. No tool writes data, and
the server never executes SQL an agent wrote: metadata comes from SQLAlchemy Inspector and fixed
catalog queries, and
execute_sqlruns only a validated, regeneratedSELECT. - Multiple servers, isolated policies - one MCP process can expose multiple named SQL Server, MySQL, and MariaDB instances. Each alias has its own connection, access level, and, when enabled, PII key and protection rules. Every database operation targets an explicit alias; there is no network discovery.
Operational safeguards
- Fails closed - SQL validation is an allowlist. Unknown syntax, unresolved lineage, and unsupported protected-value types are refused, not guessed at. The verification evidence is in the security model.
- Least access first -
access_level: metadata(the default) exposes database navigation and table structure;meta_and_codeadditionally exposes stored procedures;execute_sqlneeds an explicitall_pii_safealias with its own key. Database permissions stay the primary control, so use a least-privilege login. - Secrets stay out of sight - connection URLs live in YAML with
${NAME}placeholders resolved from the environment. They never appear in logs or model-visible errors. - Compact, predictable output - object-rooted results with stable sorting, literal case-insensitive name filters, and stored procedure lists that do not expand definitions.
- Errors an agent can act on - an ambiguous name lists the candidate schemas. Errors never contain connection details, credentials, keys, tokens, or rows.
- Tested against attacks, not just examples - the SQL and PII boundary is checked with an adversarial corpus of hostile statements, property-based tests (token isolation, tamper resistance), a live attack run against a really writable login with before/after snapshots, and mutation testing. Results are in Verification of the SQL boundary.
- Diagnosable failures - a timeout or connection error carries a
Reference, and the stderr log records the connection stage, elapsed time, and driver error for the same reference, with credentials removed. See Logging.
| Tool | Access | Purpose |
|---|---|---|
list_servers |
🟢 read | Configured server aliases |
list_databases |
🟢 read | Databases visible to the credentials |
list_tables |
🟢 read | Base tables, filtered by schema or name |
get_table_definition |
🟢 read | Columns, keys, constraints, and indexes of one table |
list_stored_procedures |
🟢 read | Stored procedures, without definitions; requires meta_and_code or all_pii_safe |
get_stored_procedure |
🟢 read | The definition of one stored procedure; requires meta_and_code or all_pii_safe |
execute_sql |
🟢 read | One restricted SELECT on an all_pii_safe server; protected columns return tokens |
[!NOTE] Status: SQL Server supports every tool. MySQL and MariaDB (
engine: mysqlormariadb,mysql+pymysqlURLs) support every tool too.schemais alwaysnullthere because the database is the catalog, andexecute_sqlusesLIMITinstead ofTOP. See architecture.md.
Quick start
Install
uvx sql-safe-mcp
or
pip install sql-safe-mcp
Pin a version when you want a fixed surface: uvx sql-safe-mcp==2.0.0.
Requires Python 3.12–3.14, uv (or pip), and
Microsoft ODBC Driver 18 for SQL Server
when you connect to SQL Server. MySQL and MariaDB use the bundled PyMySQL driver and need nothing
else.
Verified against SQL Server 2022, MySQL 8.4, and MariaDB 11.4 (see checks.md).
Install sql-safe-mcp as a stdio MCP server.
Ask whether to install it for this project/workspace or at user level. Then:
detect and preserve the host's existing MCP config;
configure the server to run via uvx sql-safe-mcp;
create a YAML config template with env placeholders only;
add SQL_SAFE_MCP_CONFIG;
report the env variables the user must set.
Do not store secrets or connection data in tracked files or output. Validate with
sql-safe-mcp --check-config once variables are available.
Configure server
Copy sql-safe-mcp.example-simple.yaml to
sql-safe-mcp.yaml. This smallest configuration exposes schema metadata from one SQL Server
instance and does not allow row queries. Keep the complete connection URL in an environment
variable:
version: 1
servers:
reporting:
engine: sqlserver
access_level: metadata
connection_url: "${REPORTING_SQL_URL}"
Here reporting is the value an agent passes as server. A missing variable, or an engine that
does not match the URL dialect, stops the MCP server at startup. For multiple servers, local PII
rules, shared PII rule sets, logging, and runtime limits, use the commented examples in the
configuration reference.
Check the configuration
After defining every environment variable referenced by the YAML file, point the server at it with
SQL_SAFE_MCP_CONFIG (or --config) and check it without connecting to any database:
SQL_SAFE_MCP_CONFIG=sql-safe-mcp.yaml uvx sql-safe-mcp --check-config
Configuration is validated at startup, and an error names the problem without printing a URL or secret. Keep credentials in the host's own configuration and never commit them. The server acts with the database account's permissions, so use a dedicated login with the least access the job needs.
Connect an MCP client
Every client configuration needs SQL_SAFE_MCP_CONFIG plus the environment variables referenced
by your YAML file. Keep connection URLs and PII keys in the MCP host's environment or
configuration, never in the YAML file or other tracked files.
claude mcp add --env SQL_SAFE_MCP_CONFIG=/path/to/sql-safe-mcp.yaml --env REPORTING_SQL_URL=mssql+pyodbc://... --transport stdio sql-safe -- uvx sql-safe-mcp
Put at least one other option between the last --env and the server name, as above. Otherwise,
the CLI reads the name as another KEY=value pair.
Add the server to claude_desktop_config.json:
{
"mcpServers": {
"sql-safe": {
"command": "uvx",
"args": ["sql-safe-mcp"],
"env": {
"SQL_SAFE_MCP_CONFIG": "/path/to/sql-safe-mcp.yaml",
"REPORTING_SQL_URL": "mssql+pyodbc://..."
}
}
}
}
codex mcp add sql-safe --env SQL_SAFE_MCP_CONFIG=/path/to/sql-safe-mcp.yaml --env REPORTING_SQL_URL=mssql+pyodbc://... -- uvx sql-safe-mcp
Use command uvx, argument sql-safe-mcp, and set SQL_SAFE_MCP_CONFIG plus every environment
variable referenced by the configuration file. The server writes MCP messages to stdout and logs
only to stderr.
PII-safe queries
execute_sql on the billing alias allows one restricted SELECT. For example, these arguments:
{
"server": "billing",
"database": "Billing",
"sql": "SELECT CustomerId, Email FROM dbo.Customers"
}
can return a row such as [42, "pii:v1:..."]: the agent can follow the customer without reading
the email address. A token is accepted only in = and IN predicates on the same server alias.
If FirstName is protected, SELECT FirstName FROM Users WHERE FirstName = 'Alice' is rejected
before it reaches the database. Filter protected columns only with authentic pii:v1:... tokens
returned by execute_sql for the same alias; a matching prefix alone is not enough. Each token is
authenticated and alias-bound, then validated and converted to a bound database value.
Protection covers the columns you list, so list every column that holds personal data.
Hardening for sensitive data
An all_pii_safe alias requires verified TLS in its connection_url and fails at startup without
it; require_tls: false turns the check off and logs a warning at every start
(Verified TLS). Every other control below is opt-in:
- Protect by default -
pii.mode: deny-by-defaultprotects every column not listed inpii.exposed_columns, andpii.denyrejects any query that references a listed column (Deny-by-default). - Check rules against the schema -
sql-safe-mcp --verify-pii-rules [--strict]reports what each rule matches and flags unprotected columns whose names look personal (Verifying PII rules). - Limit token reuse - rules with different
domainvalues reject each other's tokens, andruntime.token_ttl_secondsexpires old tokens (Token domains, Token lifetime). - Keep the key out of the environment -
pii_key_filereads the key from a file whose owner and permissions are checked at startup (Key file). - Suppress small counts -
runtime.min_count_cellreturns small nonzeroCOUNT(*)values asnull(Runtime limits). - Audit reads -
logging.audit: truelogs the tables and columns eachexecute_sqlcall read, without SQL, values, or rows (Audit log).
Tokens hide values but are pseudonyms, not anonymization: what a token still reveals is listed in the security model. For medical deployments, see Health data of minors.
Documentation
- Configuration reference - aliases, connection URLs, PII rules, runtime limits, and logging.
- Tool reference - arguments, responses, errors, and the accepted SQL subset.
- Security model - trust boundaries, guarantees, limitations, and verification.
- Health data of minors - requirements, mechanisms, and an operator checklist for medical deployments.
- Checks - local, integration, and security verification commands.
Security
The MCP caller, SQL input, database metadata, rows, and tokens are untrusted. Database permissions remain the primary authorization control - this server never widens them. Read the full security model, including its limitations and verification evidence. To report a vulnerability, use the private channel in SECURITY.md.
Contributing
Setup, checks, the test commands, the branch and commit conventions, and the release model are in CONTRIBUTING.md. Changes that affect someone running the server are recorded in CHANGELOG.md.
License
MIT.
Pertanyaan tentang sql-safe MCP
Bagaimana cara menambahkan sql-safe MCP ke Claude Code?
Jalankan claude mcp add sql-mini-mcp -- uvx sql-mini-mcp di terminal Anda. Tambahkan --scope user agar tersedia di semua proyek.
Bagaimana cara menambahkan sql-safe MCP ke Cursor?
Buka ~/.cursor/mcp.json dan tambahkan server di bawah mcpServers, menggunakan config Cursor yang ditunjukkan di bagian instalasi di atas.
Database apa saja yang didukung oleh server ini?
Server ini mendukung SQL Server, MySQL, dan MariaDB.
Apakah server ini bisa menulis data ke database saya?
Tidak, server ini dirancang sebagai read-only dan semua tool ditandai sebagai read-only untuk mencegah modifikasi data.
Bagaimana server ini melindungi PII (Personally Identifiable Information)?
Kolom PII yang telah dikonfigurasi akan dikembalikan sebagai token terautentikasi yang terikat alias, bukan dalam bentuk plaintext, sehingga agent dapat melakukan filter atau menghitung record tanpa melihat data aslinya.
Bisakah saya menggunakan ini dengan SQL Server?
Ya, SQL Server didukung sepenuhnya dan setiap tool tersedia untuknya.