sqlserver-mcp

🗄️ 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

---

📦 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)"

1. 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.

1. 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

1. 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

1. Adicione as ferramentas ao PATH (opcional):

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

1. 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

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

• Baixe em: https://www.python.org/downloads/
• Durante a instalação, marque "Add Python to PATH"

1. 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 .

1. Crie o arquivo .env com suas credenciais:

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

1. Execute o container:

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

1. 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

| Ferramenta | Descrição | Parâmetros | |------------|-----------|------------| | test_connection() | Valida conexão e retorna versão do SQL Server | - | | pool_stats() | Retorna estatísticas do pool de conexões | - |

Exploração de Schema

| Ferramenta | Descrição | Parâmetros | |------------|-----------|------------| | list_schemas() | Lista schemas disponíveis | - | | list_tables(schema?) | Lista tabelas do banco | schema (opcional) | | list_views(schema?) | Lista views do banco | schema (opcional) | | list_procedures(schema?) | Lista stored procedures | schema (opcional) | | list_functions(schema?) | Lista funções do usuário | schema (opcional) |

Análise de Tabelas

| Ferramenta | Descrição | Parâmetros | |------------|-----------|------------| | describe_table(table_name, schema?) | Descreve colunas de uma tabela | table_name, schema | | get_indexes(table_name, schema?) | Retorna índices da tabela | table_name, schema | | get_primary_key(table_name, schema?) | Retorna chave primária | table_name, schema | | get_foreign_keys(table_name, schema?) | Retorna chaves estrangeiras | table_name, schema | | get_table_relationships(table_name, schema?) | Retorna todos os relacionamentos | table_name, schema | | get_table_row_count(table_name, schema?) | Contagem aproximada de linhas | table_name, schema |

Execução de Consultas

| Ferramenta | Descrição | Parâmetros | |------------|-----------|------------| | run_query(sql, max_rows?) | Executa consulta SELECT/CTE | sql, max_rows (padrão: 1000) |

---

🔐 Variáveis de Ambiente

| Variável | Obrigatório | Padrão | Descrição | |----------|-------------|--------|-----------| | SQLSERVER_SERVER | ✅ Sim | - | Endereço do servidor | | SQLSERVER_DATABASE | Não | - | Nome do banco de dados | | SQLSERVER_USERNAME | Condicional | - | Usuário para autenticação | | SQLSERVER_PASSWORD | Condicional | - | Senha para autenticação | | SQLSERVER_PORT | Não | 1433 | Porta do servidor | | SQLSERVER_DRIVER | Não | ODBC Driver 18 for SQL Server | Driver ODBC | | SQLSERVER_ENCRYPT | Não | yes | Criptografar conexão | | SQLSERVER_TRUST_SERVER_CERTIFICATE | Não | no | Confiar em certificado autoassinado | | SQLSERVER_TRUSTED_CONNECTION | Não | no | Usar autenticação Windows | | SQLSERVER_LOG_LEVEL | Não | INFO | Nível de log (DEBUG/INFO/WARNING/ERROR) | | SQLSERVER_POOL_SIZE | Não | 5 | Tamanho máximo do pool de conexões | | SQLSERVER_POOL_IDLE_TIME | Não | 300 | Tempo máximo de ociosidade (segundos) |

\* 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

| Código | Categoria | Descrição | |--------|-----------|-----------| | E101 | Conexão | Falha na conexão | | E102 | Conexão | Timeout | | E201 | Configuração | Configuração ausente | | E301 | Validação | Erro de validação de entrada | | E303 | Segurança | Query bloqueada por segurança | | E401 | Execução | Erro na query | | E402 | Execução | Tabela não encontrada | | E404 | Execução | Permissão negada |

---

💡 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: ``env SQLSERVER_TRUST_SERVER_CERTIFICATE=yes `` > ⚠️ Não use em produção!

Porta Não Padrão

SQLSERVER_PORT=1434

Debug

Para logs detalhados: ``env SQLSERVER_LOG_LEVEL=DEBUG ``

Pool de Conexões

Para ajustar o pool conforme sua carga: ``env 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.