Mcp Sqlserver

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

| Ferramenta | Descricao | |------------|-----------| | current_connection | Mostra servidor, porta, banco ativo, permissao e cache | | list_databases | Lista bancos acessiveis no SQL Server atual | | list_schemas | Lista todos os schemas do banco | | list_tables | Lista tabelas e views agrupadas por schema | | find_tables | Busca tabelas e views por nome | | describe_table | Mostra colunas, PK, FK, checks, identity e computed | | list_indexes | Lista indices, key columns e included columns | | table_stats | Mostra rows, tamanho e datas da tabela | | find_columns | Busca colunas por nome em todas as tabelas | | relationship_map | Mostra o mapa de relacionamentos de um schema | | list_procedures | Lista procedures e functions | | query | Executa SQL respeitando as regras de permissao | | permissions | Mostra o modo atual e operacoes permitidas/bloqueadas | | sample_values | Retorna amostras distintas de valores por coluna | | query_with_explanation | Executa query de leitura e adiciona interpretacao curta | | switch_database | Troca o banco ativo da sessao atual sem reiniciar o MCP | | switch_port | Troca a porta SQL Server da sessao atual sem reiniciar o MCP | | switch_connection | Troca porta, usuario, senha e banco juntos com uma unica reconexao | | refresh_metadata | Recarrega o catalogo em cache | | health | Mostra estado da conexao e metricas do cache | | find_entities | Busca entidades por linguagem natural | | schema_summary | Resume schemas e tabelas mais conectadas | | explain_table | Explica o papel provavel de uma tabela | | suggest_join_path | Sugere joins a partir do grafo de FKs | | plan_query | Gera um plano de consulta a partir de um objetivo | | validate_query | Analisa SQL antes da execucao |

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

| Variavel | Obrigatoria | Padrao | Descricao | |----------|-------------|--------|-----------| | DB_SERVER | Nao | localhost | Host do SQL Server | | DB_DATABASE | Sim | - | Banco inicial da sessao | | DB_USER | Nao | - | Usuario SQL; se omitido usa Windows Auth | | DB_PASSWORD | Nao | - | Senha SQL | | DB_PORT | Nao | 1433 | Porta do SQL Server; ignorada em instancia nomeada | | DB_ENCRYPT | Nao | false | Habilita criptografia na conexao com SQL Server | | DB_TRUST_SERVER_CERTIFICATE | Nao | true | Confia no certificado do servidor sem validacao completa | | DB_ALLOW_WRITE | Nao | - | Operacoes de escrita permitidas | | DB_ALLOW_TABLES | Nao | - | Restringe escrita a tabelas especificas | | DB_ALLOW_SCHEMAS | Nao | - | Restringe escrita a schemas especificos | | DB_ALLOW_DATABASE_SWITCH | Nao | - | Allowlist opcional de bancos permitidos para switch_database | | DB_METADATA_TTL_MS | Nao | 300000 | TTL do cache de metadata em ms | | DB_QUERY_TIMEOUT_MS | Nao | 30000 | Timeout das queries em ms | | DB_DEFAULT_MAX_ROWS | Nao | 100 | Limite padrao de linhas para leitura | | DB_SAMPLE_SIZE | Nao | 5 | Quantidade padrao do sample_values |

Formatos de DB_SERVER

| Formato | Exemplo | |---------|---------| | Host local | localhost | | IP | 192.168.1.100 | | Nome da maquina | SERVIDOR-SQL | | Instancia nomeada com \\ | LAPTOP-ABC\\SQLEXPRESS | | Instancia nomeada com / | LAPTOP-ABC/SQLEXPRESS |

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: WendellOttoni
• Source: WendellOttoni/mcp-sqlserver
• License: MIT

Install and usage instructions live in the source repository linked above.