Sqlserver

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

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

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:

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.