Database-mcp

ArchitectureArchitettura

A single.NET console application that speaks MCP over stdio. Claude launches the process; JSON-RPC flows over stdin/stdout while all logging goes to stderr so it never corrupts the protocol stream. Un'unica applicazione console.NET che comunica tramite MCP su stdio. Claude avvia il processo; i messaggi JSON-RPC transitano su stdin/stdout, mentre tutto il logging viene scritto su stderr, così da non corrompere mai il flusso del protocollo.

Claude  <--stdio(JSON-RPC)-->  DatabaseMcp.dll
                                   │
                        ModelContextProtocol SDK
                         (tool discovery/dispatch)
                                   │
                    ┌──────────────┴──────────────┐
                 Tools/                          Data/
          SchemaTools, DataTools          ISchemaService, QueryService
          (MCP-facing, arg parsing,       (DbConnection/DbCommand —
           error translation)             provider-agnostic ADO.NET)
                                                   │
                                            Security/
                                    SqlGuard (read-only SELECT guard)
                                    SqlIdentifier (provider-aware quoting)
                                                   │
                                   ┌───────────────┴───────────────┐
                            SQL Server                        PostgreSQL
                       (Azure SQL or on-prem)          (Microsoft.Data.SqlClient / Npgsql)

MCP toolsStrumenti MCP

Eight tools cover schema navigation, structured queries, raw SQL, and bulk export. Otto strumenti coprono la navigazione dello schema, query strutturate, SQL grezzo ed esportazione massiva.

ToolStrumento	PurposeScopo
list_schemas	List user schemas (system schemas excluded) Elenca gli schemi utente (esclusi gli schemi di sistema)
list_tables	List tables, optionally filtered by schema, with approximate row counts Elenca le tabelle, filtrabili per schema, con conteggio righe approssimativo
list_views	List views, optionally filtered by schema Elenca le viste, filtrabili per schema
describe_table	Columns, primary key, foreign keys, indexes, approximate row count Colonne, chiave primaria, chiavi esterne, indici, conteggio righe approssimativo
describe_view	Columns and SQL definition for a view Colonne e definizione SQL di una vista
execute_sql	Run a raw read-only SELECT / WITH statement; CSV/TXT inline, row-capped Esegue un'istruzione SELECT / WITH grezza e di sola lettura; CSV/TXT inline, con limite di righe
query_data	Query a table/view via structured columns/filters/order/limit — no raw SQL needed Interroga una tabella/vista con colonne/filtri/ordinamento/limite strutturati — senza SQL grezzo
export_data	Stream the full result of a SELECT to a CSV/TXT file on disk Trasferisce in streaming il risultato completo di una SELECT in un file CSV/TXT su disco

Safety modelModello di sicurezza

Every code path only ever runs read-only SELECT statements against the database. Ogni percorso di codice esegue esclusivamente istruzioni SELECT di sola lettura sul database.

●

Guarded raw SQL.SQL grezzo protetto.

execute_sql and export_data reject anything that isn't a single SELECT (optionally with a leading WITH CTE) — no INSERT/UPDATE/DELETE/MERGE/DDL/EXEC/multiple statements. execute_sql ed export_data rifiutano tutto ciò che non è una singola SELECT (eventualmente con una WITH CTE iniziale) — niente INSERT/UPDATE/DELETE/MERGE/DDL/EXEC/istruzioni multiple.

●

No injection surface in query_data.Nessuna superficie di injection in query_data.

Structured queries are built server-side: identifiers are validated and bracketed, filter values are always bound as parameters. Le query strutturate vengono costruite lato server: gli identificatori sono validati e racchiusi tra parentesi, i valori dei filtri sono sempre passati come parametri.

●

Context-safe by default.Sicuro per il contesto, di default.

Inline results are capped at a configurable row count to protect the LLM's context window; responses report whether output was truncated. I risultati inline sono limitati a un numero di righe configurabile per proteggere la finestra di contesto dell'LLM; le risposte indicano se l'output è stato troncato.

●

Streaming export, no buffering.Esportazione in streaming, senza buffering.

export_data streams directly from the DbDataReader to disk, so extracting millions of rows never loads them fully into memory. export_data trasferisce i dati direttamente dal DbDataReader al disco, così estrarre milioni di righe non le carica mai completamente in memoria.

TechnologyTecnologia

• .NET 10 / C# Console app, net10.0 Applicazione console, net10.0
• ModelContextProtocol SDK Official C# MCP SDK — stdio transport, tool discovery SDK ufficiale C# per MCP — trasporto stdio, discovery degli strumenti
• Microsoft.Data.SqlClient SQL Server connectivity — Azure SQL and on-prem Connettività a SQL Server — Azure SQL e on-premise
• Npgsql PostgreSQL connectivity Connettività a PostgreSQL
• Microsoft.Extensions.Hosting Generic host, dependency injection, logging Generic host, dependency injection, logging
• xUnit Unit + integration test suite in tests/DatabaseMcp.Tests Suite di test unitari e di integrazione in tests/DatabaseMcp.Tests
• No ORMNessun ORM Hand-written, parameterized ADO.NET for predictable streaming performance ADO.NET scritto a mano e parametrizzato, per prestazioni di streaming prevedibili

Project statusStato del progetto

101 / 101 tests passing101 / 101 test superati — 91 unit tests plus 10 integration tests exercised against both a live SQL Server and a live PostgreSQL instance. — 91 test unitari e 10 test di integrazione eseguiti sia contro un'istanza reale di SQL Server sia contro una reale di PostgreSQL.

Read-only by designDi sola lettura per progettazione

Every tool routes through the SQL guard or the parameterized query builder — never raw concatenation. Ogni strumento passa attraverso il guard SQL o il costruttore di query parametrizzate — mai concatenazione diretta.

One database engine per instanceUn motore database per istanza

A DB_PROVIDER switch (sqlserver or postgresql) selects the engine; run two instances to reach both at once. Un interruttore DB_PROVIDER (sqlserver o postgresql) seleziona il motore; avvia due istanze per raggiungerli entrambi.

Azure SQL & on-premAzure SQL e on-premise

Falls back to Windows Integrated Security when no credentials are supplied. Ricade automaticamente su Windows Integrated Security se non vengono fornite credenziali.

Ships with a Claude skillInclude una skill per Claude

skill/SKILL.md teaches Claude the recommended orient → inspect → query → export workflow. skill/SKILL.md insegna a Claude il flusso di lavoro consigliato: orientarsi → ispezionare → interrogare → esportare.

QuickstartAvvio rapido

Build the solution, then point an MCP client at the compiled DLL. Compila la soluzione, quindi punta un client MCP alla DLL compilata.

dotnet build -c Release
dotnet test

Add it to Claude Desktop or Claude Code using claude_desktop_config.example.json as a template — fill in your real host and credentials. Aggiungilo a Claude Desktop o Claude Code usando claude_desktop_config.example.json come modello — inserisci il tuo host e le tue credenziali reali.