DbLens.Mcp
0.1.3
{ "inputs": [ { "type": "promptString", "id": "ConnectionStrings__PostgreSql", "description": "PostgreSQL connection string for a read-only login.", "password": true }, { "type": "promptString", "id": "ConnectionStrings__SqlServer", "description": "SQL Server connection string for a read-only login.", "password": true } ], "servers": { "DbLens.Mcp": { "type": "stdio", "command": "dnx", "args": ["DbLens.Mcp@0.1.3", "--yes"], "env": { "ConnectionStrings__PostgreSql": "${input:ConnectionStrings__PostgreSql}", "ConnectionStrings__SqlServer": "${input:ConnectionStrings__SqlServer}" } } } }
.vscode/mcp.json settings file.
dotnet tool install --global DbLens.Mcp --version 0.1.3
dotnet new tool-manifest
dotnet tool install --local DbLens.Mcp --version 0.1.3
#tool dotnet:?package=DbLens.Mcp&version=0.1.3
nuke :add-package DbLens.Mcp --version 0.1.3
dblens
An MCP server, written in .NET 10, that lets Claude (or any MCP client) understand and diagnose PostgreSQL and SQL Server databases. It runs locally, never writes to the database, and by default never returns row data.
Install
Releases are built by
.github/workflows/release.ymlwhen av*tag is pushed. The NuGet package is published with Trusted Publishing once it is configured (see docs/architecture.md#releases); until then use the release downloads.
Claude Desktop — download dblens-<version>-<platform>.mcpb from
Releases, open it, and fill in the connection
strings when asked.
Any MCP client, with the .NET 10 runtime — install the tool and point the client at it:
dotnet tool install -g DbLens.Mcp
claude mcp add dblens -e "ConnectionStrings__PostgreSql=Host=…;Username=dblens_reader;Password=…" -- dblens
Without .NET — the release also carries self-contained binaries (dblens-<version>-<rid>.zip);
use the extracted DbLens.Mcp executable as the command.
From source — see Quick start.
Use a read-only login for any shared database. dblens refuses to execute caller SQL on a login
that can write when the server is on another machine, so create one first — two statements, in
docs/safety.md. A database on your own machine (localhost,
loopback, socket, (local), LocalDB) is exempt: the admin login works there.
Tools
| Tool | Answers |
|---|---|
ping |
Is the server up? |
get_schema |
What tables and views are there, how big? |
get_table_details |
Columns, indexes, keys and constraints of these tables |
infer_relationships |
How do tables join — including foreign keys nobody declared, found in views, routines and query history? |
build_glossary |
Write me a data map of this database as a skill |
analyze_indexes |
Which FKs lack an index, which indexes are duplicate, redundant or unused? |
analyze_fragmentation |
Which indexes are fragmented or sparsely packed? |
analyze_denormalization |
Where is data repeated, cached or packed into one column — and has it drifted? |
scan_gdpr |
Which columns look like personal data? |
check_cascade_paths |
What does a DELETE on this table actually remove? |
check_migration_safety |
Will this migration lock, rewrite or destroy anything, given real table sizes? |
explain_query |
Why is this query slow? |
query_with_receipt |
What is the figure, and what is the proof? (off unless the operator enables it) |
certify_query, list_certified_queries |
Remember the queries the user confirmed as right |
Full parameters, rules and limits: docs/tools.md.
A typical session: get_schema to orient, infer_relationships and build_glossary to learn the
structure, then the diagnostic tool that fits the question. For a slow query start from
explain_query; before shipping DDL run it through check_migration_safety.
Facts and guesses are kept apart
Every diagnostic tool returns two lists:
Findings— what dblens established: measured (fragmentation, scan counters, counted rows) or derived from the catalog (a cascade cycle, a duplicate index, the lock a DDL takes).Signals— what it suspects from names, structure or the SQL the database runs.fiscal_codeprobably holds a fiscal code. Or nothing. Or something else.
They are separate lists, not a flag, because a flag disappears the moment a response is summarized.
Two tools can test their own guesses. With verifySignals / verifyCandidates, dblens runs one
generated, read-only, rolled-back aggregate query per checkable signal and moves the measured ones into
Findings:
shipments.ship_tois joined toaddresses.idby the viewshipment_destinations(signal)
becomes
all 6 non-null values exist in
public.addresses(finding, measured, with theALTER TABLEto declare it)
Probes return counts only — how many rows, never which ones.
Answers with a receipt
When the operator enables it (DbLens:AllowQueryResults=true), query_with_receipt answers with the
figure and the evidence: the exact SQL, the tables the plan read, and — given a second query that
computes the same figure another way — whether the two agree. If they disagree, dblens says so instead
of choosing. Queries the user confirms can be certified and re-run by name; the glossary lists them.
It is off by default because it is the one tool that returns values from the data. What runs, and what stops it from doing harm: docs/safety.md.
Quick start
Requires the .NET 10 SDK and, for the demo databases, Docker.
cp .env.example .env
docker compose up -d # PostgreSQL on 5433, SQL Server on 1434 (~1 min the first time)
dotnet build
dotnet test
dotnet run --project src/DbLens.Mcp
The server then waits on stdin: that is the MCP stdio transport working. To use a build from source in Claude Code:
claude mcp add dblens dotnet -- run --project "C:\path\to\dblens\src\DbLens.Mcp"
Configuration
Key (appsettings.json) |
Environment variable | Default |
|---|---|---|
ConnectionStrings:PostgreSql |
ConnectionStrings__PostgreSql |
the demo database, as dblens_reader |
ConnectionStrings:SqlServer |
ConnectionStrings__SqlServer |
the demo database, as dblens_reader |
DbLens:AllowQueryResults |
DbLens__AllowQueryResults |
false — enables query_with_receipt |
DbLens:AllowWriteCapableLogin |
DbLens__AllowWriteCapableLogin |
false — skips the read-only-login check on remote servers too; disposable databases only |
DbLens:ReadOnlyLoginOnLocalhost |
DbLens__ReadOnlyLoginOnLocalhost |
false — applies the check to a local server as well, for dblens installed on a real database server |
DbLens:CertifiedQueriesPath |
DbLens__CertifiedQueriesPath |
%LOCALAPPDATA%/dblens/certified-queries.json |
A tool call can also pass its own connectionString. analyze_fragmentation additionally needs
pgstattuple (PostgreSQL) or VIEW DATABASE STATE (SQL Server); query history needs
pg_stat_statements or Query Store.
Demo logins:
PostgreSQL Host=localhost;Port=5433;Database=dblens_demo;Username=dblens_reader;Password=readerpassword
SQL Server Server=localhost,1434;Database=dblens_demo;User Id=dblens_reader;Password=ReaderPassword123!;TrustServerCertificate=true
Demo databases
public / dbo is an e-commerce schema with deliberate flaws — unindexed foreign keys, duplicate
indexes, plaintext PII, cascade chains, cached counts that have drifted, undeclared references (one
visible only through a view). demo_good is a clean design on which every tool reports nothing.
Details in docs/architecture.md.
Documentation
| Document | For |
|---|---|
| docs/tools.md | Every tool: parameters, rules, severities, limits |
| docs/safety.md | The contract, what can execute, the read-only login |
| docs/architecture.md | How the code is organized, pipelines, testing, releases |
| GLOSSARY.md | Finding, signal, evidence, probe, receipt… |
| DEVELOPMENT.md | Dev workflows, MCP Inspector, debugging (Italian) |
| CLAUDE.md | Conventions for contributors and coding agents |
Licence
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
This package has no dependencies.