mcp-sqlserver

Servidor MCP (Model Context Protocol) para SQL Server, com controle de permissões e modo somente-leitura por padrão. Permite que agentes de IA (Claude, opencode e outros clientes MCP) consultem e administrem bancos SQL Server de forma segura.

Segurança

Credenciais nunca expostas ao LLM — a string de conexão é lida do ambiente e nunca aparece nas respostas nem nos logs.
Somente leitura por padrão — a ferramenta consulta bloqueia DDL/DML (INSERT, UPDATE, DELETE, DROP, etc.).
Escrita sob demanda — ferramentas de escrita (executar_update, executar_ddl, etc.) só são expostas quando o usuário da conexão possui permissão de escrita (roles sysadmin, db_owner, db_datawriter ou db_ddladmin), e exigem confirmação explícita antes de cada execução.

Pré-requisitos

Python 3.10+
Driver ODBC Driver 18 for SQL Server:
- macOS: brew install msodbcsql18
- Windows/Linux: instale o driver correspondente da Microsoft

Instalação

Via PyPI:

bash

pip install sqlserver-mcp-tools

Ou, sem instalar nada (executa direto do PyPI com cache):

bash

uvx --from sqlserver-mcp-tools mcp-sqlserver

Configuração

O servidor lê a string de conexão das seguintes fontes, em ordem de prioridade:

Variável de ambiente MSSQL_CONNECTION_STRING
Variável de ambiente MSSQL_ENV_FILE apontando para um arquivo .env
Arquivo .env no diretório de trabalho (ou na raiz do projeto)

Exemplo de string de conexão:

DRIVER={ODBC Driver 18 for SQL Server};SERVER=localhost,1433;DATABASE=seu_banco;UID=seu_usuario;PWD=sua_senha;TrustServerCertificate=yes

Uso com clientes MCP

Claude Desktop

Adicione ao claude_desktop_config.json:

json

{
  "mcpServers": {
    "mcp-sqlserver": {
      "command": "uvx",
      "args": ["--from", "sqlserver-mcp-tools", "mcp-sqlserver"],
      "env": {
        "MSSQL_CONNECTION_STRING": "DRIVER={ODBC Driver 18 for SQL Server};SERVER=...;DATABASE=...;UID=...;PWD=...;TrustServerCertificate=yes"
      }
    }
  }
}

Se instalou via pip install, pode usar o entry point diretamente:

json

{
  "mcpServers": {
    "mcp-sqlserver": {
      "command": "mcp-sqlserver",
      "env": {
        "MSSQL_CONNECTION_STRING": "DRIVER={ODBC Driver 18 for SQL Server};SERVER=...;DATABASE=...;UID=...;PWD=...;TrustServerCertificate=yes"
      }
    }
  }
}

OpenCode

No opencode.json do projeto:

json

{
  "mcp": {
    "sqlserver": {
      "type": "local",
      "command": ["mcp-sqlserver"],
      "environment": {
        "MSSQL_CONNECTION_STRING": "DRIVER={ODBC Driver 18 for SQL Server};SERVER=...;DATABASE=...;UID=...;PWD=...;TrustServerCertificate=yes"
      }
    }
  }
}

Alternativa: apontar para um arquivo .env local, mantendo a senha fora do JSON:

json

{
  "mcp": {
    "sqlserver": {
      "type": "local",
      "command": ["mcp-sqlserver"],
      "environment": {
        "MSSQL_ENV_FILE": "/caminho/para/seu/.env"
      }
    }
  }
}

Servidor HTTP (Streamable HTTP)

Além do modo local (stdio), o servidor pode ser executado como um MCP remoto via Streamable HTTP, expondo o endpoint /mcp. Instale com o extra server:

bash

pip install 'sqlserver-mcp-tools[server]'

Inicie o servidor:

bash

MSSQL_CONNECTION_STRING="DRIVER={ODBC Driver 18 for SQL Server};SERVER=...;DATABASE=...;UID=...;PWD=...;TrustServerCertificate=yes" \
  mcp-sqlserver-http

Opcionalmente, ajuste host/porta com MCP_HOST (padrão 0.0.0.0) e MCP_PORT (padrão 8090). O endpoint MCP fica em http://<host>:<porta>/mcp.

Para consumir remotamente no opencode:

json

{
  "mcp": {
    "sqlserver": {
      "type": "remote",
      "url": "http://10.177.51.228:8090/mcp"
    }
  }
}

Ferramentas disponíveis

Somente leitura (sempre disponíveis):

Ferramenta	Descrição
`consulta`	Executa SELECT (somente leitura, bloqueia DDL/DML)
`listar_bancos`	Lista os bancos de dados acessíveis
`listar_tabelas`	Lista tabelas e views de um banco
`descrever_tabela`	Estrutura de uma tabela (colunas, tipos, PK)
`listar_indices`	Índices de uma tabela
`listar_procedures`	Lista stored procedures
`ler_procedure`	Código-fonte de uma procedure
`listar_funcoes`	Lista funções (scalar e table-valued)
`ler_funcao`	Código-fonte de uma função
`listar_constraints`	Constraints de uma tabela (PK, FK, UNIQUE, CHECK, DEFAULT)
`estatisticas_tabela`	Estatísticas (linhas, tamanho, uso de dados)
`plano_execucao`	Plano de execução estimado (sem executar)
`status_jobs`	Status da última execução de jobs do SQL Agent

Escrita (só com permissão de escrita na conexão):

Ferramenta	Descrição
`executar_procedure`	Executa uma stored procedure
`executar_update`	Executa UPDATE (exige WHERE)
`criar_indice`	Cria índice
`alterar_procedure`	Altera procedure com backup automático
`executar_ddl`	Executa DDL com backup do script de reversão