MCP SQL Server

Servidor MCP (Model Context Protocol) para Microsoft SQL Server. Permite que Claude Code, Codex, Cursor, Windsurf, Cline, Continue e outras ferramentas MCP explorem schema, relacionamentos e executem consultas SQL com foco em seguranca.

O que ele faz

• Explora schemas, tabelas, colunas, indices, procedures e foreign keys

• Monta ranking por intencao com find_entities

• Sugere caminhos de join com suggest_join_path

• Gera plano de consulta com plan_query

• Valida SQL antes de executar com validate_query

• Executa SELECT e, opcionalmente, escrita controlada por permissoes

• Mantem catalogo em memoria com cache e refresh

• Permite trocar o banco ativo em runtime com switch_database

• Permite trocar a porta ativa em runtime com switch_port

• Permite trocar porta, usuario, senha e banco em uma unica acao com switch_connection

• Lista bancos acessiveis no servidor com list_databases

• Mostra a conexao ativa com current_connection

• Retorna respostas em formato visual com box-drawing ASCII/Unicode durante a execucao das tools

Ferramentas disponiveis

Sobre este README

Este arquivo fica em Markdown normal para leitura no GitHub e nas IDEs. O visual com box-drawing ASCII/Unicode aparece apenas na execucao das tools do MCP, nas respostas retornadas para Claude, Codex, Cursor e clientes compativeis.

Requisitos

• Node.js 18 ou superior

• Acesso a um SQL Server local ou remoto

Instalacao

git clone https://github.com/WendellOttoni/mcp-sqlserver.git
cd mcp-sqlserver
npm install

Configuracao MCP

Exemplo de .mcp.json:

{
  "mcpServers": {
    "sqlserver": {
      "command": "node",
      "args": ["C:/MCP/mcp-sqlserver/src/index.js"],
      "env": {
        "DB_SERVER": "localhost",
        "DB_DATABASE": "MeuBanco",
        "DB_USER": "sa",
        "DB_PASSWORD": "MinhaSenha"
      }
    }
  }
}

Voce tambem pode usar o template em .mcp.json.example.

Variaveis de ambiente

Formatos de DB_SERVER

Se usar /, o MCP converte automaticamente para o formato de instancia nomeada.

Modo de permissao

Por padrao o servidor sobe em modo READ-ONLY. Sem DB_ALLOW_WRITE, apenas consultas de leitura sao permitidas.

Exemplo:

{
  "DB_ALLOW_WRITE": "INSERT,UPDATE",
  "DB_ALLOW_TABLES": "dbo.Produto,dbo.Pedido"
}

Operacoes permanentemente bloqueadas:

EXEC, EXECUTE, GRANT, REVOKE, DENY, BACKUP, RESTORE, SHUTDOWN, DBCC, BULK, OPENROWSET, OPENDATASOURCE, xp_*, sp_*

Troca de banco em runtime

Agora nao e mais necessario reiniciar o processo MCP para apontar para outro banco no mesmo servidor.

Fluxo recomendado:

1. Rode current_connection para confirmar onde a sessao esta conectada.

2. Rode list_databases para ver os bancos acessiveis.

3. Rode switch_database para trocar o banco ativo.

4. Rode schema_summary ou list_schemas para explorar o novo banco.

Use:

switch_database { "database": "OutroBanco" }

Comportamento:

• valida a nova conexao antes de trocar

• carrega o catalogo do novo banco antes de assumir a sessao

• fecha o pool antigo apenas depois da validacao

• se a troca falhar, a conexao atual continua ativa

Observacao:

• switch_database troca apenas o banco ativo

• server, user, password e outras configuracoes permanecem as mesmas

• list_databases oculta master, model, msdb e tempdb por padrao

• use include_system_databases: true para incluir bancos de sistema

Para limitar quais bancos podem ser usados em switch_database, configure:

{
  "DB_ALLOW_DATABASE_SWITCH": "ReqPlay,Homologacao,Teste"
}

Se DB_ALLOW_DATABASE_SWITCH nao for definida, qualquer banco acessivel pelo login atual pode ser usado.

Troca de porta em runtime

Use switch_port para apontar a sessao atual para outra porta TCP do mesmo servidor sem reiniciar o chat ou perder o contexto da IA.

Fluxo recomendado:

1. Rode current_connection para ver servidor, porta e banco atuais.

2. Rode switch_port com a nova porta.

3. Rode current_connection, schema_summary ou list_schemas para confirmar a nova conexao.

Use:

switch_port { "port": 1450 }

Comportamento:

• valida a nova conexao antes de trocar

• carrega o catalogo usando a nova porta antes de assumir a sessao

• fecha o pool antigo apenas depois da validacao

• se a troca falhar, a conexao atual continua ativa

Observacao:

• switch_port troca apenas a porta

• server, database, user, password e outras configuracoes permanecem as mesmas

• em DB_SERVER com instancia nomeada, a porta e gerenciada pela instancia e switch_port nao e aplicado

Troca completa de conexao em runtime

Use switch_connection quando precisar trocar porta, usuario, senha e banco de uma vez so, com apenas uma validacao e uma reconexao ao final.

Use:

switch_connection {
  "port": 51218,
  "user": "sa",
  "password": "Docker@Test123",
  "database": "master"
}

Comportamento:

• todos os parametros sao opcionais

• qualquer campo omitido mantem o valor atual

• a troca so e assumida depois que a nova conexao completa for validada

• o pool antigo so e fechado no final, apos validar e carregar o catalogo

Exemplos de configuracao

Somente leitura:

{
  "DB_SERVER": "localhost",
  "DB_DATABASE": "MeuBanco"
}

SQL Auth:

{
  "DB_SERVER": "localhost",
  "DB_DATABASE": "MeuBanco",
  "DB_USER": "sa",
  "DB_PASSWORD": "MinhaSenha"
}

Instancia nomeada:

{
  "DB_SERVER": "LAPTOP-ABC/SQLEXPRESS",
  "DB_DATABASE": "MeuBanco"
}

Escrita restrita por tabela:

{
  "DB_SERVER": "localhost",
  "DB_DATABASE": "MeuBanco",
  "DB_ALLOW_WRITE": "INSERT,UPDATE",
  "DB_ALLOW_TABLES": "dbo.Produto,dbo.Pedido"
}

Escrita restrita por schema:

{
  "DB_SERVER": "localhost",
  "DB_DATABASE": "MeuBanco",
  "DB_ALLOW_WRITE": "INSERT,UPDATE,DELETE",
  "DB_ALLOW_SCHEMAS": "staging"
}

Servidor remoto com porta customizada:

{
  "DB_SERVER": "192.168.1.100",
  "DB_PORT": "1450",
  "DB_DATABASE": "Producao",
  "DB_USER": "app_user",
  "DB_PASSWORD": "SenhaSegura"
}

Servidor remoto com TLS validado:

{
  "DB_SERVER": "sql.empresa.local",
  "DB_PORT": "1433",
  "DB_DATABASE": "Producao",
  "DB_USER": "app_user",
  "DB_PASSWORD": "SenhaSegura",
  "DB_ENCRYPT": "true",
  "DB_TRUST_SERVER_CERTIFICATE": "false"
}

Ferramentas de analise

As ferramentas abaixo usam metadata carregada em memoria para responder mais rapido:

• find_entities

• schema_summary

• explain_table

• suggest_join_path

• plan_query

• refresh_metadata

• health

Seguranca

• READ-ONLY por padrao

• Escrita controlada por operacao, schema e tabela

• Validacao de SQL antes da execucao

• Limite maximo de 1000 linhas no fluxo de leitura

• Cache de metadata com TTL configuravel

• Validacao de conexao logo no startup

• Troca de banco em runtime com validacao antes do cutover

Estrutura do projeto

mcp-sqlserver/
|-- .mcp.json.example
|-- README.md
|-- package.json
|-- src/
|   |-- config/
|   |   `-- env.js
|   |-- db/
|   |   |-- catalog-cache.js
|   |   |-- catalog-loader.js
|   |   `-- connection.js
|   |-- graph/
|   |   `-- relationship-graph.js
|   |-- search/
|   |   |-- aliases.js
|   |   `-- ranker.js
|   |-- security/
|   |   |-- permissions.js
|   |   `-- sql-validator.js
|   |-- tools/
|   |   |-- core.js
|   |   `-- intelligence.js
|   |-- utils/
|   |   |-- formatting.js
|   |   `-- text.js
|   `-- index.js
`-- test/
    |-- sample-values.test.js
    `-- security.test.js

Desenvolvimento

Executar o servidor:

npm start

Rodar os testes:

npm test