Microsoft SQL Server MCP

Um servidor MCP baseado em .NET para interagir com bancos de dados Microsoft SQL Server.

GitHub
155
Experimente este MCPPatrocinado

Documentação

mssql-mcp

Um servidor Model Context Protocol (MCP) baseado em .NET para Microsoft SQL Server.

Resumo

Por que isso existe? Porque as outras soluções MCP no mercado para isso são geralmente porcarias que não funcionam - certamente não no Windows.

Este servidor MCP fornece aos agentes de IA acesso robusto e confiável a bancos de dados Microsoft SQL Server por meio de um aplicativo .NET limpo e bem arquitetado, usando Akka.NET para coordenação interna e o SDK oficial MCP C# para conformidade com o protocolo.

Recursos

  • Descoberta de Esquema: Agentes de IA podem explorar a estrutura do banco de dados sem escrever SQL complexo
  • Execução de Consultas: Suporte completo a SQL para operações SELECT, INSERT, UPDATE, DELETE e DDL
  • Validação de Conexão: Validação automática de conectividade do banco de dados na inicialização
  • Tratamento de Erros: Tratamento abrangente de erros com mensagens de erro claras e acionáveis
  • Formatação de Tabelas: Resultados de consultas formatados em tabelas legíveis para consumo por IA
  • Suporte a Docker: Implantação fácil com ferramentas Docker integradas ao .NET

Ferramentas Disponíveis

FerramentaDescrição
execute_sqlExecuta qualquer consulta SQL no banco de dados
list_tablesLista todas as tabelas com esquema, nome, tipo e contagem de linhas
list_schemasLista todos os esquemas/bancos de dados disponíveis na instância do SQL Server

Configuração

Variáveis de Ambiente Obrigatórias

O servidor MCP requer uma única variável de ambiente:

  • MSSQL_CONNECTION_STRING: String de conexão completa do SQL Server

Exemplos de Strings de Conexão

Autenticação do Windows:

MSSQL_CONNECTION_STRING="Server=localhost;Database=MyDatabase;Trusted_Connection=true;"

Autenticação do SQL Server:

MSSQL_CONNECTION_STRING="Server=localhost;Database=MyDatabase;User Id=myuser;Password=mypassword;"

Banco de Dados SQL do Azure:

MSSQL_CONNECTION_STRING="Server=myserver.database.windows.net;Database=mydatabase;User Id=myuser;Password=mypassword;Encrypt=true;"

Executando o Servidor MCP

Opção 1: Docker (Recomendado)

A maneira mais fácil de executar o servidor MCP é usando Docker com o suporte a contêineres integrado do .NET.

Compilar e Executar com Docker

Clone o repositório

Clone o repositório

git clone https://github.com/Aaronontheweb/mssql-mcp.git cd mssql-mcp

Compile a imagem Docker

dotnet publish --os linux --arch x64 /t:PublishContainer

Você pode executar o contêiner diretamente se desejar, mas é provavelmente melhor deixar o servidor MCP iniciar o cliente:

Execute o contêiner

docker run -it --rm
-e MSSQL_CONNECTION_STRING="Server=host.docker.internal;Database=MyDB;Trusted_Connection=true;"
mssql-mcp:latest

Configuração do Cliente MCP

IDE Cursor

Adicione às configurações do Cursor (Cursor Settings > Features > Model Context Protocol):

{ "mcpServers": { "mssql": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "MSSQL_CONNECTION_STRING", "mssql-mcp:latest" ], "env": { "MSSQL_CONNECTION_STRING": "Server=host.docker.internal,1533; Database=MyDb; User Id=myUser; Password=My(!)Password;TrustServerCertificate=true;" } } } }

Claude Desktop

Adicione ao arquivo de configuração do Claude Desktop:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Talvez seja necessário criar esse arquivo e reiniciar o Claude Desktop para que as alterações tenham efeito.

Entendendo Sua Configuração de Servidor MCP do Claude Desktop

Esta configuração JSON é para os servidores Model Context Protocol (MCP) do Claude Desktop. Ela essencialmente ensina o Claude a se conectar e usar uma "ferramenta" personalizada que interage com um banco de dados Microsoft SQL Server (MSSQL).

Vamos detalhar cada parte:

mcpServers

Esta é a seção de nível superior onde você define todos os seus servidores MCP personalizados. Você pode configurar vários servidores aqui, cada um com seu próprio nome exclusivo.

"mssql"

Este é o nome exclusivo que você escolheu para esta integração específica do SQL Server. O Claude usará este nome para se referir a esta conexão de banco de dados.

"command": "docker"

Esta linha informa ao Claude Desktop para iniciar o servidor MCP usando Docker. Isso significa que o software do servidor real é executado dentro de um contêiner isolado, e você precisará do Docker Desktop instalado e em execução na sua máquina Windows/mac/Linux para que isso funcione. Alternativamente, você pode usar um servidor Docker remoto usando contexto personalizado.

"args": [...]

Estes são os argumentos que o Claude Desktop passa ao comando docker ao iniciar o contêiner:

  • "run": Este comando Docker padrão cria e inicia um novo contêiner.
  • "-i": Significa "interativo", mantendo a entrada padrão aberta para comunicação entre o servidor MCP e o Claude Desktop.
  • "--rm": Este argumento importante informa ao Docker para remover automaticamente o contêiner quando ele parar. Isso ajuda a manter seu ambiente Docker organizado.
  • "-e", "MSSQL_CONNECTION_STRING": Isso passa uma variável de ambiente chamada MSSQL_CONNECTION_STRING para dentro do contêiner Docker.
  • "mssql-mcp:latest": Isso especifica a imagem Docker a ser usada. Esta imagem (mssql-mcp com a tag latest) contém o aplicativo servidor MCP real projetado para interagir com o SQL Server. Você precisará garantir que esta imagem esteja disponível (compilada localmente ou baixada de um registro Docker).
"env": {...}

Esta seção define as variáveis de ambiente que serão definidas quando o Docker executar o comando.

  • "MSSQL_CONNECTION_STRING": "Server=host.docker.internal,1533; Database=MyDb; User Id=myUser; Password=My(!)Password;TrustServerCertificate=true;"
    • Esta é a string de conexão do SQL Server que o contêiner Docker mssql-mcp usará para se conectar ao seu banco de dados.
    • Server=host.docker.internal,1533: host.docker.internal é um nome DNS especial do Docker que permite que o contêiner alcance o endereço IP da sua máquina host. É assim que o servidor MCP dentro do Docker pode se conectar à sua instância do SQL Server, que presumivelmente está sendo executada diretamente na sua máquina. 1533 é a porta em que seu SQL Server está escutando.
    • Database=MyDb: O nome do banco de dados específico ao qual você deseja se conectar.
    • User Id=myUser; Password=My(!)Password;: As credenciais de um usuário (myUser) para fazer login no seu SQL Server.
    • TrustServerCertificate=true;: Isso informa ao cliente para pular a validação do certificado SSL/TLS do servidor. Embora seja conveniente para desenvolvimento ou ao usar certificados autoassinados, esteja ciente de que isso reduz a segurança, tornando você vulnerável a ataques man-in-the-middle em ambientes de produção.
Em Resumo:

Esta configuração permite que o Claude Desktop execute um servidor MCP específico do SQL Server dentro de um contêiner Docker. Este servidor então usa a string de conexão fornecida para estabelecer uma conexão com seu banco de dados SQL Server, permitindo que o Claude interaja com seus dados por meio desta ferramenta personalizada.

Configuração de Binário Local

Se estiver executando o binário compilado diretamente em vez do Docker:

{ "mcpServers": { "mssql": { "command": "/path/to/mssql-mcp/src/MSSQL.MCP/bin/Release/net9.0/MSSQL.MCP", "env": { "MSSQL_CONNECTION_STRING": "Server=localhost;Database=MyDB;Trusted_Connection=true;" } } } }

Problemas de Rede com Docker

Entendendo o Problema

Ao executar o servidor MCP como um contêiner Docker, você encontrará desafios de rede ao tentar se conectar a instâncias do SQL Server em execução na sua máquina host ou em outros contêineres. Os contêineres Docker são isolados da rede do host por padrão, tornando conexões localhost impossíveis.

Soluções por Cenário

Cenário 1: SQL Server em Execução na Máquina Host

Problema: Seu SQL Server está instalado diretamente no Windows/macOS/Linux, e você deseja que o servidor MCP conteinerizado se conecte a ele.

Solução: Use host.docker.internal em vez de localhost na sua string de conexão.

❌ Isso não funcionará - localhost se refere ao próprio contêiner

docker run -it --rm
-e MSSQL_CONNECTION_STRING="Server=localhost;Database=MyDB;User Id=sa;Password=YourPassword123!;"
mssql-mcp:latest

✅ Isso funciona - host.docker.internal se refere à máquina host

docker run -it --rm
-e MSSQL_CONNECTION_STRING="Server=host.docker.internal;Database=MyDB;User Id=sa;Password=YourPassword123!;"
mssql-mcp:latest

Configuração Atualizada do Cliente MCP:

{ "mcpServers": { "mssql": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "MSSQL_CONNECTION_STRING=Server=host.docker.internal;Database=MyDB;User Id=sa;Password=YourPassword123!;", "mssql-mcp:latest" ] } } }

Cenário 2: SQL Server em Outro Contêiner Docker

Solução: Use Docker Compose com uma rede personalizada e referencie os contêineres pelo nome do serviço.

version: '3.8' networks: sql-network: driver: bridge

services: mssql-mcp: build: . environment: # Use o nome do serviço 'sqlserver' como nome do host - MSSQL_CONNECTION_STRING=Server=sqlserver;Database=MyDatabase;User Id=sa;Password=YourPassword123!; stdin_open: true tty: true networks: - sql-network depends_on: - sqlserver

sqlserver: image: mcr.microsoft.com/mssql/server:2022-latest environment: - ACCEPT_EULA=Y - SA_PASSWORD=YourPassword123! networks: - sql-network ports: - "1433:1433" # Expor ao host para ferramentas externas

Cenário 3: Linux com Modo de Rede do Host

Solução Apenas para Linux: Use o modo de rede host do Docker para acesso direto à rede do host.

Apenas Linux - compartilha a pilha de rede do host

docker run -it --rm --network host
-e MSSQL_CONNECTION_STRING="Server=localhost;Database=MyDB;User Id=sa;Password=YourPassword123!;"
mssql-mcp:latest

Considerações Específicas por Plataforma

Plataformahost.docker.internalModo de Rede do HostSolução Recomendada
Windows✅ Funciona imediatamente❌ Não suportadoUse host.docker.internal
macOS✅ Funciona imediatamente❌ Não suportadoUse host.docker.internal
Linux⚠️ Requer --add-host✅ SuportadoUse --network host ou host.docker.internal

Configuração host.docker.internal no Linux:

docker run -it --rm
--add-host=host.docker.internal:host-gateway
-e MSSQL_CONNECTION_STRING="Server=host.docker.internal;Database=MyDB;User Id=sa;Password=YourPassword123!;"
mssql-mcp:latest

Testando a Conectividade de Rede

Para verificar se seu contêiner pode alcançar o SQL Server:

Teste de dentro de um contêiner em execução

docker exec -it <container_name> ping host.docker.internal

Teste a porta do SQL Server especificamente

docker run --rm -it mcr.microsoft.com/mssql-tools
/bin/bash -c "sqlcmd -S host.docker.internal -U sa -P 'YourPassword123!' -Q 'SELECT @@VERSION'"

Solução de Problemas Comuns de Rede

  1. Conexão Recusada:
    • Verifique se o SQL Server está escutando em todas as interfaces: netstat -an | grep 1433
    • Verifique se o Firewall do Windows permite acesso à sub-rede do Docker
  2. Resolução de DNS:
    • Teste: docker run --rm busybox nslookup host.docker.internal
    • Certifique-se de que o Docker Desktop esteja em execução (para Windows/macOS)
  3. Contêiner para Contêiner:
    • Verifique se ambos os contêineres estão na mesma rede Docker
    • Use nomes de serviço dos contêineres, não localhost
  4. Conflitos de Porta:
    • Certifique-se de que a porta 1433 não esteja já vinculada por outro processo
    • Verifique com: netstat -tlnp | grep 1433

Exemplos de Uso

Uma vez configurado, os agentes de IA podem usar linguagem natural para interagir com seu banco de dados:

"Mostre-me todas as tabelas no banco de dados"→ Usa a ferramenta list_tables

"Descreva a estrutura da tabela Users"→ Usa execute_sql com uma consulta INFORMATION_SCHEMA

"Encontre todos os usuários criados nos últimos 30 dias"→ Usa execute_sql com uma consulta SELECT apropriada

"Crie um novo registro de cliente"→ Usa execute_sql com uma instrução INSERT

Considerações de Segurança

⚠️ Avisos Importantes de Segurança

  • Permissões de Banco de Dados: Conceda apenas as permissões mínimas necessárias ao usuário do banco de dados
  • Segurança de Conexão: Use conexões criptografadas para ambientes de produção
  • Controle de Acesso: Este servidor MCP fornece capacidades completas de execução SQL - garanta controles de acesso adequados
  • Registro de Auditoria: Considere habilitar o registro de auditoria do SQL Server para uso em produção
  • Segurança de Rede: Restrinja o acesso à rede ao servidor de banco de dados de forma adequada

Permissões Recomendadas de Banco de Dados

Para acesso somente leitura:

-- Criar um usuário dedicado com permissões mínimas CREATE LOGIN mcp_readonly WITH PASSWORD = 'SecurePassword123!'; CREATE USER mcp_readonly FOR LOGIN mcp_readonly;

-- Conceder apenas as permissões necessárias GRANT SELECT ON SCHEMA::dbo TO mcp_readonly; GRANT VIEW DEFINITION ON SCHEMA::dbo TO mcp_readonly;

Para acesso de leitura e escrita:

-- Criar um usuário dedicado CREATE LOGIN mcp_readwrite WITH PASSWORD = 'SecurePassword123!'; CREATE USER mcp_readwrite FOR LOGIN mcp_readwrite;

-- Conceder as permissões necessárias GRANT SELECT, INSERT, UPDATE, DELETE ON SCHEMA::dbo TO mcp_readwrite; GRANT VIEW DEFINITION ON SCHEMA::dbo TO mcp_readwrite;

Solução de Problemas

Problemas de Conexão

  1. Verifique a string de conexão: Teste com o SQL Server Management Studio ou Azure Data Studio
  2. Verifique o firewall: Garanta que a porta do SQL Server (padrão 1433) esteja acessível
  3. Habilite o TCP/IP: Garanta que o protocolo TCP/IP esteja habilitado no SQL Server Configuration Manager
  4. Modo de autenticação: Verifique se o SQL Server está configurado para o modo de autenticação apropriado

Problemas com Contêineres

  1. Conectividade de rede: Use host.docker.internal em vez de localhost ao conectar do contêiner ao host
  2. Variáveis de ambiente: Garanta que a string de conexão esteja devidamente escapada nos comandos Docker
  3. Logs: Verifique os logs do contêiner com docker logs <container_id>

Licença

Este software é licenciado sob Apache 2.0 e está disponível "como está" - isso significa que se você detonar seu banco de dados porque deu acesso sa a um agente de IA através deste servidor MCP, não somos responsáveis.

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Faça suas alterações
  4. Adicione testes se aplicável
  5. Envie um pull request

Arquitetura

  • Akka.NET: Usado para coordenação interna do sistema de atores e validação de banco de dados
  • MCP C# SDK: Implementação oficial do Model Context Protocol
  • Microsoft.Data.SqlClient: Conectividade de alto desempenho com o SQL Server