Microsoft SQL Server MCP

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

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 instáveis 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 de C# do MCP 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 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 do .NET

Ferramentas Disponíveis

Ferramenta	Descrição
`execute_sql`	Executa qualquer consulta SQL no banco de dados
`list_tables`	Lista todas as tabelas com esquema, nome, tipo e contagem de linhas
`list_schemas`	Lista 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

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 the repository
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 preferir, mas é provavelmente melhor deixar o servidor MCP iniciar o cliente:

# Run the container
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

{
  "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;"
      }
    }
  }
}

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

Entendendo Sua Configuração do Servidor MCP no 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 do servidor MCP real projetado para interagir com o SQL Server. Você precisará garantir que esta imagem esteja disponível (compilada localmente ou obtida 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 conectar-se 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 de intermediário 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 do 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.

# ❌ This won't work - localhost refers to the container itself
docker run -it --rm \
  -e MSSQL_CONNECTION_STRING="Server=localhost;Database=MyDB;User Id=sa;Password=YourPassword123!;" \
  mssql-mcp:latest

# ✅ This works - host.docker.internal refers to the host machine
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 the service name 'sqlserver' as the hostname
      - 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"  # Expose to host for external tools

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

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

# Linux only - shares the host's network stack
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

Plataforma	host.docker.internal	Modo de Rede do Host	Solução Recomendada
Windows	✅ Funciona imediatamente	❌ Não suportado	Use `host.docker.internal`
macOS	✅ Funciona imediatamente	❌ Não suportado	Use `host.docker.internal`
Linux	⚠️ Requer `--add-host`	✅ Suportado	Use `--network host` ou `host.docker.internal`

Configuração do 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:

# Test from inside a running container
docker exec -it <container_name> ping host.docker.internal

# Test SQL Server port specifically
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

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 o acesso à sub-rede do Docker
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)
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
Conflitos de Porta:
- Certifique-se de que a porta 1433 não esteja já vinculada a outro processo
  - Verifique com: netstat -tlnp | grep 1433

Exemplos de Uso

Uma vez configurados, 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 Usuários" → 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 do Banco de Dados: Conceda apenas as permissões mínimas necessárias ao usuário do banco de dados
Segurança da 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 adequadamente o acesso à rede do servidor de banco de dados

Para acesso somente leitura:

-- Create a dedicated user with minimal permissions
CREATE LOGIN mcp_readonly WITH PASSWORD = 'SecurePassword123!';
CREATE USER mcp_readonly FOR LOGIN mcp_readonly;

-- Grant only necessary permissions
GRANT SELECT ON SCHEMA::dbo TO mcp_readonly;
GRANT VIEW DEFINITION ON SCHEMA::dbo TO mcp_readonly;

Para acesso de leitura e escrita:

-- Create a dedicated user
CREATE LOGIN mcp_readwrite WITH PASSWORD = 'SecurePassword123!';
CREATE USER mcp_readwrite FOR LOGIN mcp_readwrite;

-- Grant necessary permissions
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

Verifique a string de conexão: Teste com o SQL Server Management Studio ou Azure Data Studio
Verifique o firewall: Certifique-se de que a porta do SQL Server (padrão 1433) esteja acessível
Habilite TCP/IP: Certifique-se de que o protocolo TCP/IP esteja habilitado no Gerenciador de Configuração do SQL Server
Modo de autenticação: Verifique se o SQL Server está configurado para o modo de autenticação apropriado

Problemas com Contêineres

Conectividade de rede: Use host.docker.internal em vez de localhost ao conectar do contêiner ao host
Variáveis de ambiente: Certifique-se de que a string de conexão esteja devidamente escapada nos comandos Docker
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ê destruir completamente seu banco de dados porque deu acesso sa a um agente de IA por meio deste servidor MCP, não somos responsáveis.