elekto-mcp-sql

# Elekto.Mcp.Sql

<!-- mcp-name: io.github.elekto-com-br/elekto-mcp-sql -->

[![.NET](https://img.shields.io/badge/.NET-10-512BD4)](https://dotnet.microsoft.com)
[![NuGet](https://img.shields.io/nuget/v/Elekto.Mcp.Sql.svg)](https://www.nuget.org/packages/Elekto.Mcp.Sql)
[![NuGet Downloads](https://img.shields.io/nuget/dt/Elekto.Mcp.Sql.svg)](https://www.nuget.org/packages/Elekto.Mcp.Sql)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![CI](https://github.com/elekto-com-br/elekto-mcp-sql/actions/workflows/ci.yml/badge.svg)](https://github.com/elekto-com-br/elekto-mcp-sql/actions/workflows/ci.yml)
[![elekto-com-br/elekto-mcp-sql MCP server](https://glama.ai/mcp/servers/elekto-com-br/elekto-mcp-sql/badges/score.svg)](https://glama.ai/mcp/servers/elekto-com-br/elekto-mcp-sql)

Read-only MCP server for SQL Server 2017+ introspection and querying (tested on 2019 and 2022).
Exposes schema metadata, object definitions, and data queries via the MCP protocol (stdio),
allowing GitHub Copilot (and other MCP clients, like Claude, etc.) to understand your database structure
without storing credentials in the repository.

## ⚠️ Privacy and Data Security Warning

MCP servers act as a bridge between your local data and AI language models. When you use
this server with an AI assistant (such as GitHub Copilot, Claude, or others), the following
happens:

1. The AI agent calls tools on this server to read data from your SQL Server database.
2. The results — which may include table schemas, stored procedure definitions, or actual
   row data — are sent back to the AI agent and transmitted to the LLM provider's
   infrastructure for analysis.
3. **This means your data leaves your machine and is sent to a third-party service**
   (Microsoft, Anthropic, OpenAI, etc.), subject to their respective terms of service
   and privacy policies.

Before connecting this server to any database, carefully consider:

- What data could be read? Does it include PII, financial records, trade secrets,
  or other sensitive information?
- Who is the LLM provider and what are their data retention and privacy policies?
- Are you authorized to share this data with that third party under applicable laws
  and regulations?

**Recommendations:**

- Never connect to databases containing sensitive data unless you have explicitly assessed
  and accepted this risk.
- Use database accounts with the minimum required privileges (read-only, restricted to
  specific schemas where possible).
- Use `max_query_rows` to limit how much data can be returned in a single call.
- Prefer databases with anonymized or synthetic data for development and exploration.
- AI agents can be **extremely creative** in finding ways to execute a task. Altouht this server 
  is designed to be read-only and to validate all inputs, **there is always a risk of 
  unintended consequences** when exposing database access to an AI agent.

**Regardless of the precautions you take, the responsibility for any consequences arising
from the use of this tool rests entirely with you.** This software is provided *as is*
with no warranties of any kind.

## Available Tools

| Tool                       | Description                                                  |
| -------------------------- | ------------------------------------------------------------ |
| `list_databases`           | Databases registered in the configuration                    |
| `get_database_overview`    | High-level database summary (counts, size, connection metadata), and whether the login sees everything |
| `check_permissions`        | What the connected login can and cannot see, the GRANT that completes it, and whether it could write |
| `get_schema_summary`       | Aggregated metrics by schema (objects, rows, size)           |
| `list_schemas`             | Schemas in a database (excluding system schemas)             |
| `list_tables`              | User tables with schema, dates, approximate rows and estimated size; filterable by schema and name pattern |
| `list_views`               | User views, filterable by schema and name pattern            |
| `find_columns`             | Every table and view holding a column whose name matches a pattern |
| `list_procedures`          | User stored procedures (with basic complexity metrics)       |
| `list_functions`           | User-defined functions (with basic complexity metrics)       |
| `get_table_schema`         | Columns with unambiguous type declarations, all extended properties, PKs, FKs, checks, uniques and indexes with key order and declared key width |
| `get_view_definition`      | DDL definition + columns of a view, with the same column detail |
| `get_procedure_definition` | CREATE PROCEDURE text                                        |
| `get_function_definition`  | CREATE FUNCTION text                                         |
| `get_dependency_graph`     | Object dependency edges (FK + SQL dependencies)              |
| `get_table_usage`          | References to a table across FKs and SQL modules             |
| `get_data_profile`         | Column profile (null ratio, distinct count, min/max, top values) |
| `get_index_health`         | Duplicate/unused index diagnostics + missing-index suggestions |
| `compare_schemas`          | Compares table/column structure between two configured databases |
| `generate_dependency_dot`  | Graphviz DOT dependency graph with node metadata (`node_kind`) |
| `query_table`              | SELECT from a table or view with filtering, grouping, secure aggregates, sorting, sampling and pagination |

## Upgrading from 1.x

Version 2.0.0 changes what the tools return and how their parameters are declared. Nothing
needs reconfiguring — connection files, `.mcp.json` and the CLI arguments are unchanged —
but anything that parses the output will notice:

| Change | What to do |
| ------ | ---------- |
| `query_table` returns an object, not an array | Read the rows from `rows`; check `truncated` |
| Failures return `ok: false` content instead of raising a tool error | Test for `ok === false` before treating the payload as data |
| Column results gained `type_declaration`, `max_length_chars`, `is_persisted` and `extended_properties` | Prefer `type_declaration` over `max_length`, which is bytes |
| `description` on a column is now an alias for `extended_properties.MS_Description` | Nothing; it still works |
| Optional tool parameters are no longer nullable | Nothing over MCP. Direct C# callers pass `""` (or `0`) instead of `null` |
| New: `find_columns`; `list_tables` and `list_views` take a `name_pattern` | Nothing; both are additive |

Everything else — every other tool, every other field — is unchanged.

## What changed in 2.1.0

Nothing changes shape: arrays are still arrays and objects keep every field they had. A few
values now say "unknown" instead of passing a guess for a fact, which is worth knowing if you
parse them:

| Change | Why |
| ------ | --- |
| New: `check_permissions` | Says what the login is missing, per tool, with the GRANT that fixes it |
| `get_database_overview`, `get_table_usage`, `get_index_health` and `generate_dependency_dot` gained a `visibility` block | So a result the login could only partly see says so |
| `list_procedures` / `list_functions` rows gained `definition_visible`; `line_count` and `join_count` are `null` when it is false | A hidden definition used to read as a body of 0 lines |
| `referenced_object_count` is `null`, and `get_table_usage`'s `sql_module_usage` is `null`, when the login cannot read `sys.sql_expression_dependencies` | Both used to fail the whole call with error 229 |
| `get_index_health` returns the duplicates and `null` for the DMV sections when the login lacks the server permission | It used to fail outright, losing the part that needs no permission |
| `get_*_definition` of a name the login cannot see returns `ok: false` instead of `[]` | `[]` read the same for "does not exist" and "hidden from you" |
| SQL errors carry their number, and the hint tells permission, missing name and syntax apart | One generic hint covered all three |

## What changed in 2.2.0

No tool result changes shape. What changes is how the server starts and how it is packaged:

| Change | Why |
| ------ | --- |
| The server starts without any connection, states it in its server instructions, and every tool answers `ok: false` with the file to create, where it looked and an example | A server that exited at startup showed only as "failed", and failed in every project when registered for all of them |
| A configuration that cannot be read (invalid JSON, a `%{VARIABLE}` that is not set, a `--connections` file that is missing or empty) is reported the same way, instead of ending the process | The error now reaches whoever calls the tools |
| While nothing is loaded, every call looks for the configuration again | A connections file created after the server started is used without a restart |
| The package is listed among nuget.org's MCP servers and carries `.mcp/server.json` | So it can be found there, with a ready configuration on its **MCP Server** tab |

The process no longer exits with code 1 when the configuration is missing or unreadable. Anything
that relied on that exit code should read a tool's answer instead. The README also gained setup
instructions for [Claude Code](#claude-code-setup) and [Codex](#codex-setup).

## What changed in 2.3.0

No tool result changes shape; what changes is what the tools say about themselves, which is what an
agent chooses them by:

| Change | Why |
| ------ | --- |
| Every tool declares a title and the MCP annotations `readOnlyHint`, `idempotentHint`, `destructiveHint: false` and `openWorldHint: false` | Clients can show the tools as safe, and agents need not infer it from prose |
| Every description says what the tool does, when to use it and which tool to use instead | So an agent picks the right one of 21 tools th