Allows AI agents to securely query and manage SQL Server databases with built-in read-only protections and permission controls.
Also known as hlgurgel/mcp-sqlserver, mcp-sqlserver, sqlserver-mcp-tools
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- 398
- Latest version
- 0.1.8
- Last commit
- Oct 11, 2026
- License
- MIT
What is SQL MCP?
SQL allows AI agents to securely query and manage SQL Server databases with built-in read-only protections and permission controls.
Summary generated from the project's README
About SQL MCP server
Querying and managing SQL Server databases through AI agents is made safer with this MCP server. It provides a secure way for clients like Claude Desktop or OpenCode to interact with your data while maintaining strict permission controls. The system operates with a read-only default mode, meaning the consulta tool automatically blocks any DDL or DML commands like INSERT or DELETE to prevent accidental data modification.
Developers can run this server locally via stdio or as a remote service using Streamable HTTP. Setup requires Python 3.10 or higher and the ODBC Driver 18 for SQL Server. Connection strings are managed through environment variables like MSSQL_CONNECTION_STRING or a .env file, ensuring sensitive credentials are never exposed to the LLM. Write-access tools such as executar_update or executar_ddl only appear if the connection user holds specific roles like sysadmin or db_owner and require explicit confirmation before running.
Beyond simple queries, the server offers deep inspection capabilities. You can use tools to list databases, describe table structures, view stored procedure source code, or examine execution plans. This makes it a comprehensive interface for both database exploration and administrative tasks.
What you can do with it
- 1Safe database explorationAsk an AI to inspect your database schema and table structures without risking any data changes.
- 2Analyzing stored proceduresRequest the AI to read and explain the logic within your existing SQL functions or procedures.
- 3Database performance auditingHave an agent review execution plans and table statistics to identify potential bottlenecks.
Written from the project's README. Every use case is checked against a quote from it.
How to install SQL MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall SQL MCP in Claude Code
$ claude mcp add --env 'MSSQL_CONNECTION_STRING=<YOUR_MSSQL_CONNECTION_STRING>' mcp-sqlserver -- uvx sqlserver-mcp-toolsInstall SQL MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-sqlserver": {
"command": "uvx",
"args": [
"sqlserver-mcp-tools"
],
"env": {
"MSSQL_CONNECTION_STRING": "<YOUR_MSSQL_CONNECTION_STRING>"
}
}
}
}Install SQL MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-sqlserver": {
"type": "stdio",
"command": "uvx",
"args": [
"sqlserver-mcp-tools"
],
"env": {
"MSSQL_CONNECTION_STRING": "<YOUR_MSSQL_CONNECTION_STRING>"
}
}
}
}Install SQL MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-sqlserver","type":"stdio","command":"uvx","args":["sqlserver-mcp-tools"],"env":{"MSSQL_CONNECTION_STRING":"<YOUR_MSSQL_CONNECTION_STRING>"}}'Install SQL MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-sqlserver": {
"command": "uvx",
"args": [
"sqlserver-mcp-tools"
],
"env": {
"MSSQL_CONNECTION_STRING": "<YOUR_MSSQL_CONNECTION_STRING>"
}
}
}
}Install SQL MCP in Codex
$ codex mcp add mcp-sqlserver --env 'MSSQL_CONNECTION_STRING=<YOUR_MSSQL_CONNECTION_STRING>' -- uvx sqlserver-mcp-toolsInstall SQL MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-sqlserver] command = "uvx" args = ["sqlserver-mcp-tools"] [mcp_servers.mcp-sqlserver.env] MSSQL_CONNECTION_STRING = "<YOUR_MSSQL_CONNECTION_STRING>"
Install SQL MCP in Gemini CLI
$ gemini mcp add -s user -e 'MSSQL_CONNECTION_STRING=<YOUR_MSSQL_CONNECTION_STRING>' mcp-sqlserver uvx -- sqlserver-mcp-toolsInstall SQL MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-sqlserver": {
"command": "uvx",
"args": [
"sqlserver-mcp-tools"
],
"env": {
"MSSQL_CONNECTION_STRING": "<YOUR_MSSQL_CONNECTION_STRING>"
}
}
}
}Configuration
MSSQL_CONNECTION_STRINGRequiredSecretString de conexão ODBC para o SQL Server
MSSQL_ENV_FILE
| Name | Description | |
|---|---|---|
| MSSQL_CONNECTION_STRING | String de conexão ODBC para o SQL Server | RequiredSecret |
| MSSQL_ENV_FILE | — |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablehlgurgel/mcp-sqlserver is public and reachablegithub.com/hlgurgel/mcp-sqlserver ↗Pass
- Package names this repository as its sourcesqlserver-mcp-tools names hlgurgel/mcp-sqlserver as sourcepypi.org/project/sqlserver-mcp-tools/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for sqlserver-mcp-toolspypi.org/project/sqlserver-mcp-tools/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-11github.com/hlgurgel/mcp-sqlserver ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from sqlserver-mcp-toolsPass
- No critical advisory in the package or its dependencies31 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmcp-sqlserver
Servidor MCP (Model Context Protocol) para SQL Server, com controle de permissões e modo somente-leitura por padrão. Permite que agentes de IA (Claude, opencode e outros clientes MCP) consultem e administrem bancos SQL Server de forma segura.
Segurança
- Credenciais nunca expostas ao LLM — a string de conexão é lida do ambiente e nunca aparece nas respostas nem nos logs.
- Somente leitura por padrão — a ferramenta
consultabloqueia DDL/DML (INSERT, UPDATE, DELETE, DROP, etc.). - Escrita sob demanda — ferramentas de escrita (
executar_update,executar_ddl, etc.) só são expostas quando o usuário da conexão possui permissão de escrita (rolessysadmin,db_owner,db_datawriteroudb_ddladmin), e exigem confirmação explícita antes de cada execução.
Pré-requisitos
- Python 3.10+
- Driver ODBC Driver 18 for SQL Server:
- macOS:
brew install msodbcsql18 - Windows/Linux: instale o driver correspondente da Microsoft
- macOS:
Instalação
Via PyPI:
pip install sqlserver-mcp-tools
Ou, sem instalar nada (executa direto do PyPI com cache):
uvx --from sqlserver-mcp-tools mcp-sqlserver
Configuração
O servidor lê a string de conexão das seguintes fontes, em ordem de prioridade:
- Variável de ambiente
MSSQL_CONNECTION_STRING - Variável de ambiente
MSSQL_ENV_FILEapontando para um arquivo.env - Arquivo
.envno diretório de trabalho (ou na raiz do projeto)
Exemplo de string de conexão:
DRIVER={ODBC Driver 18 for SQL Server};SERVER=localhost,1433;DATABASE=seu_banco;UID=seu_usuario;PWD=sua_senha;TrustServerCertificate=yes
Uso com clientes MCP
Claude Desktop
Adicione ao claude_desktop_config.json:
{
"mcpServers": {
"mcp-sqlserver": {
"command": "uvx",
"args": ["--from", "sqlserver-mcp-tools", "mcp-sqlserver"],
"env": {
"MSSQL_CONNECTION_STRING": "DRIVER={ODBC Driver 18 for SQL Server};SERVER=...;DATABASE=...;UID=...;PWD=...;TrustServerCertificate=yes"
}
}
}
}
Se instalou via pip install, pode usar o entry point diretamente:
{
"mcpServers": {
"mcp-sqlserver": {
"command": "mcp-sqlserver",
"env": {
"MSSQL_CONNECTION_STRING": "DRIVER={ODBC Driver 18 for SQL Server};SERVER=...;DATABASE=...;UID=...;PWD=...;TrustServerCertificate=yes"
}
}
}
}
OpenCode
No opencode.json do projeto:
{
"mcp": {
"sqlserver": {
"type": "local",
"command": ["mcp-sqlserver"],
"environment": {
"MSSQL_CONNECTION_STRING": "DRIVER={ODBC Driver 18 for SQL Server};SERVER=...;DATABASE=...;UID=...;PWD=...;TrustServerCertificate=yes"
}
}
}
}
Alternativa: apontar para um arquivo .env local, mantendo a senha fora do JSON:
{
"mcp": {
"sqlserver": {
"type": "local",
"command": ["mcp-sqlserver"],
"environment": {
"MSSQL_ENV_FILE": "/caminho/para/seu/.env"
}
}
}
}
Servidor HTTP (Streamable HTTP)
Além do modo local (stdio), o servidor pode ser executado como um MCP remoto
via Streamable HTTP, expondo o endpoint /mcp. Instale com o extra server:
pip install 'sqlserver-mcp-tools[server]'
Inicie o servidor:
MSSQL_CONNECTION_STRING="DRIVER={ODBC Driver 18 for SQL Server};SERVER=...;DATABASE=...;UID=...;PWD=...;TrustServerCertificate=yes" \
mcp-sqlserver-http
Opcionalmente, ajuste host/porta com MCP_HOST (padrão 0.0.0.0) e MCP_PORT
(padrão 8090). O endpoint MCP fica em http://<host>:<porta>/mcp.
Para consumir remotamente no opencode:
{
"mcp": {
"sqlserver": {
"type": "remote",
"url": "http://10.177.51.228:8090/mcp"
}
}
}
Ferramentas disponíveis
Somente leitura (sempre disponíveis):
| Ferramenta | Descrição |
|---|---|
consulta |
Executa SELECT (somente leitura, bloqueia DDL/DML) |
listar_bancos |
Lista os bancos de dados acessíveis |
listar_tabelas |
Lista tabelas e views de um banco |
descrever_tabela |
Estrutura de uma tabela (colunas, tipos, PK) |
listar_indices |
Índices de uma tabela |
listar_procedures |
Lista stored procedures |
ler_procedure |
Código-fonte de uma procedure |
listar_funcoes |
Lista funções (scalar e table-valued) |
ler_funcao |
Código-fonte de uma função |
listar_constraints |
Constraints de uma tabela (PK, FK, UNIQUE, CHECK, DEFAULT) |
estatisticas_tabela |
Estatísticas (linhas, tamanho, uso de dados) |
plano_execucao |
Plano de execução estimado (sem executar) |
status_jobs |
Status da última execução de jobs do SQL Agent |
Escrita (só com permissão de escrita na conexão):
| Ferramenta | Descrição |
|---|---|
executar_procedure |
Executa uma stored procedure |
executar_update |
Executa UPDATE (exige WHERE) |
criar_indice |
Cria índice |
alterar_procedure |
Altera procedure com backup automático |
executar_ddl |
Executa DDL com backup do script de reversão |
Licença
MIT
SQL MCP questions
How do I add SQL MCP to Claude Code?
Run claude mcp add --env 'MSSQL_CONNECTION_STRING=<YOUR_MSSQL_CONNECTION_STRING>' mcp-sqlserver -- uvx sqlserver-mcp-tools in your terminal. Add --scope user to make it available in every project.
How do I add SQL MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Is the connection string safe from the LLM?
Yes, credentials are never exposed to the LLM as the connection string is read from the environment and does not appear in responses or logs.
Can the AI accidentally delete or modify data?
By default, the tool is read-only and blocks DDL/DML commands like INSERT, UPDATE, or DELETE. Write tools are only exposed if the user has specific database roles and require explicit confirmation.