🗄️ Servidor MCP: SQL Server (Não Oficial)

Desenvolvido em Python por Moises Gomes

🌐 Site oficial: moigomes.github.io/sqlserver-mcp-site

Servidor MCP (Model Context Protocol) em Python para consultar Microsoft SQL Server via pyodbc, expondo ferramentas para exploração de banco de dados, execução de consultas seguras e análise de estrutura.

📋 Índice

• Pré-requisitos

• Instalação

  • macOS

  • Linux (Ubuntu/Debian)

  • Windows

  • Docker

• Configuração

• Execução

• Integração com Cursor

• Ferramentas Disponíveis

• Variáveis de Ambiente

• Segurança

• Dicas

• Outros Clientes Compatíveis

Related MCP server: Microsoft SQL Server MCP Server

📦 Pré-requisitos

• Python 3.10+

• Driver ODBC do SQL Server instalado

• Acesso a um servidor SQL Server

🚀 Instalação

macOS

1. Instale o Homebrew (se ainda não tiver):

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Instale o driver ODBC e ferramentas:

   brew update
   brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
   brew install --no-sandbox msodbcsql18 mssql-tools18
   brew install unixodbc

   ⚠️ Aceite a licença da Microsoft quando solicitado.

3. Clone o repositório e configure:

   git clone <url-do-repositorio>
   cd sqlserver-mcp
   
   # Crie o ambiente virtual
   python3 -m venv .venv
   source .venv/bin/activate
   
   # Instale as dependências
   pip install -r requirements.txt
   
   # Configure as variáveis de ambiente
   cp .env.example .env
   # Edite o arquivo .env com suas credenciais

Linux (Ubuntu/Debian)

1. Adicione o repositório da Microsoft:

   curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
   curl https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list

2. Instale o driver ODBC:

   sudo apt-get update
   sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18
   sudo ACCEPT_EULA=Y apt-get install -y mssql-tools18
   sudo apt-get install -y unixodbc-dev

3. Adicione as ferramentas ao PATH (opcional):

   echo 'export PATH="$PATH:/opt/mssql-tools18/bin"' >> ~/.bashrc
   source ~/.bashrc

4. Clone o repositório e configure:

   git clone <url-do-repositorio>
   cd sqlserver-mcp
   
   # Crie o ambiente virtual
   python3 -m venv .venv
   source .venv/bin/activate
   
   # Instale as dependências
   pip install -r requirements.txt
   
   # Configure as variáveis de ambiente
   cp .env.example .env
   nano .env  # ou use seu editor preferido

Windows

1. Baixe e instale o driver ODBC:

   • Acesse: https://learn.microsoft.com/pt-br/sql/connect/odbc/download-odbc-driver-for-sql-server

   • Baixe o "ODBC Driver 18 for SQL Server"

   • Execute o instalador e siga as instruções

2. Instale o Python (se ainda não tiver):

   • Baixe em: https://www.python.org/downloads/

   • Durante a instalação, marque "Add Python to PATH"

3. Clone o repositório e configure:

   git clone <url-do-repositorio>
   cd sqlserver-mcp
   
   # Crie o ambiente virtual
   python -m venv .venv
   .venv\Scripts\activate
   
   # Instale as dependências
   pip install -r requirements.txt
   
   # Configure as variáveis de ambiente
   copy .env.example .env
   notepad .env

🐳 Docker

A forma mais fácil de rodar o servidor sem instalar dependências localmente.

1. Build da imagem:

   docker build -t sqlserver-mcp .

2. Crie o arquivo .env com suas credenciais:

   cp .env.example .env
   # Edite o .env com suas configurações

3. Execute o container:

   # Modo interativo (para testes)
   docker run -it --env-file .env sqlserver-mcp
   
   # Ou com docker-compose
   docker-compose up -d

4. Comandos úteis:

   # Ver logs
   docker-compose logs -f
   
   # Parar
   docker-compose down
   
   # Rebuild após alterações
   docker-compose up -d --build

⚙️ Configuração

Arquivo .env

Crie um arquivo .env na raiz do projeto com as seguintes variáveis:

# Conexão obrigatória
SQLSERVER_SERVER=seu_servidor
SQLSERVER_DATABASE=seu_banco
SQLSERVER_USERNAME=seu_usuario
SQLSERVER_PASSWORD=sua_senha

# Opcionais
SQLSERVER_PORT=1433
SQLSERVER_DRIVER=ODBC Driver 18 for SQL Server
SQLSERVER_ENCRYPT=yes
SQLSERVER_TRUST_SERVER_CERTIFICATE=no
SQLSERVER_TRUSTED_CONNECTION=no

# Logging (DEBUG, INFO, WARNING, ERROR)
SQLSERVER_LOG_LEVEL=INFO

# Connection Pool
SQLSERVER_POOL_SIZE=5
SQLSERVER_POOL_IDLE_TIME=300

Autenticação Windows (Trusted Connection)

Para usar autenticação integrada do Windows:

SQLSERVER_SERVER=seu_servidor
SQLSERVER_DATABASE=seu_banco
SQLSERVER_TRUSTED_CONNECTION=yes

▶️ Execução

Modo Standalone (para testes)

# macOS/Linux
source .venv/bin/activate
python server.py

# Windows
.venv\Scripts\activate
python server.py

O servidor ficará aguardando conexões via STDIO. Use Ctrl+C para encerrar.

Teste de Conexão

Execute o cliente de teste para validar a configuração:

python client_smoke.py

🔌 Integração com Cursor

Abra as configurações do Cursor (Cmd+Shift+J ou Ctrl+Shift+J) e adicione em mcpServers:

macOS/Linux

{
  "mcpServers": {
    "sqlserver-mcp": {
      "command": "/caminho/para/sqlserver-mcp/.venv/bin/python",
      "args": ["/caminho/para/sqlserver-mcp/server.py"],
      "cwd": "/caminho/para/sqlserver-mcp",
      "env": {
        "PYTHONPATH": ".",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Windows

{
  "mcpServers": {
    "sqlserver-mcp": {
      "command": "C:\\caminho\\para\\sqlserver-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\caminho\\para\\sqlserver-mcp\\server.py"],
      "cwd": "C:\\caminho\\para\\sqlserver-mcp",
      "env": {
        "PYTHONPATH": ".",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

💡 Dica: As variáveis de ambiente podem ser definidas no arquivo .env (carregadas automaticamente) ou diretamente na configuração do Cursor.

🛠️ Ferramentas Disponíveis

Conexão e Diagnóstico

Exploração de Schema

Análise de Tabelas

Execução de Consultas

🔐 Variáveis de Ambiente

* SQLSERVER_USERNAME e SQLSERVER_PASSWORD são obrigatórios se SQLSERVER_TRUSTED_CONNECTION não estiver como yes.

🔒 Segurança

O servidor implementa múltiplas camadas de segurança:

1. Validação de Queries

• ✅ Apenas SELECT e WITH (CTEs) são permitidos

• ❌ Bloqueia: INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE

• ❌ Bloqueia: EXEC, EXECUTE, xp_*, sp_configure

• ❌ Bloqueia: OPENROWSET, OPENDATASOURCE, BULK

2. Proteção contra SQL Injection

• ❌ Múltiplos statements são bloqueados (ex: SELECT 1; DROP TABLE x)

• ✅ Queries parametrizadas são usadas internamente

3. Transação Read-Only

• Todas as queries são executadas em transação com ROLLBACK automático

• Mesmo que algo passe pelas validações, nada será persistido

Códigos de Erro

💡 Dicas

Driver ODBC

• macOS: Use SQLSERVER_DRIVER=ODBC Driver 18 for SQL Server

• Linux: Use SQLSERVER_DRIVER=ODBC Driver 18 for SQL Server

• Windows: Use SQLSERVER_DRIVER=ODBC Driver 18 for SQL Server

Certificado Autoassinado

Para ambientes de desenvolvimento com certificado autoassinado:

SQLSERVER_TRUST_SERVER_CERTIFICATE=yes

⚠️ Não use em produção!

Porta Não Padrão

SQLSERVER_PORT=1434

Debug

Para logs detalhados:

SQLSERVER_LOG_LEVEL=DEBUG

Pool de Conexões

Para ajustar o pool conforme sua carga:

SQLSERVER_POOL_SIZE=10
SQLSERVER_POOL_IDLE_TIME=600

🔌 Outros Clientes Compatíveis

Este servidor MCP pode ser usado em qualquer cliente compatível com o Model Context Protocol. A configuração é similar à do Cursor.

IDEs e Editores

• Claude Desktop (macOS, Windows) - App oficial da Anthropic

• VS Code + GitHub Copilot - Suporte MCP em preview

• Zed (macOS, Linux) - Editor moderno

• Windsurf - IDE focada em IA

• Continue - Extensão open-source para VS Code

Mobile e Desktop

• 5ire - Assistente IA desktop

• AIaW - Cliente de chat multiplataforma

• Jenova AI - Mobile + Desktop

• Systemprompt MCP (iOS) - Controle por voz

Cloud e Enterprise

• Amazon Q Developer - CLI da AWS

• Microsoft Sentinel - Segurança com MCP

📖 Lista completa de clientes: https://glama.ai/mcp/clients
📖 Especificação MCP: https://modelcontextprotocol.io

📄 Licença

Este projeto é não oficial e desenvolvido de forma independente.

🤝 Contribuições

Contribuições são bem-vindas! Abra uma issue ou pull request.