sqlserver-mcp-tools 0.1.0__tar.gz

sqlserver_mcp_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hlgurgel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sqlserver_mcp_tools-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: sqlserver-mcp-tools
+Version: 0.1.0
+Summary: Servidor MCP (Model Context Protocol) para SQL Server com controle de permissões e modo somente-leitura
+Author: hlgurgel
+License-Expression: MIT
+Project-URL: Repository, https://github.com/hlgurgel/mcp-sqlserver
+Project-URL: Issues, https://github.com/hlgurgel/mcp-sqlserver/issues
+Keywords: mcp,model-context-protocol,sql-server,sqlserver,mcp-server,pyodbc,sql
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<2.0,>=1.0.0
+Requires-Dist: pyodbc>=5.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Dynamic: license-file
+
+# mcp-sqlserver
+
+[![PyPI version](https://img.shields.io/pypi/v/sqlserver-mcp-tools.svg)](https://pypi.org/project/sqlserver-mcp-tools/)
+[![License: MIT](https://img.shields.io/github/license/hlgurgel/mcp-sqlserver.svg)](https://github.com/hlgurgel/mcp-sqlserver/blob/main/LICENSE)
+[![Python versions](https://img.shields.io/pypi/pyversions/sqlserver-mcp-tools.svg)](https://pypi.org/project/sqlserver-mcp-tools/)
+
+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:
+
+1. Variável de ambiente `MSSQL_CONNECTION_STRING`
+2. Variável de ambiente `MSSQL_ENV_FILE` apontando para um arquivo `.env`
+3. 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"
+      }
+    }
+  }
+}
+```
+
+## 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 |
+
+## Licença
+
+MIT

sqlserver_mcp_tools-0.1.0/README.md

@@ -0,0 +1,158 @@
+# mcp-sqlserver
+
+[![PyPI version](https://img.shields.io/pypi/v/sqlserver-mcp-tools.svg)](https://pypi.org/project/sqlserver-mcp-tools/)
+[![License: MIT](https://img.shields.io/github/license/hlgurgel/mcp-sqlserver.svg)](https://github.com/hlgurgel/mcp-sqlserver/blob/main/LICENSE)
+[![Python versions](https://img.shields.io/pypi/pyversions/sqlserver-mcp-tools.svg)](https://pypi.org/project/sqlserver-mcp-tools/)
+
+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:
+
+1. Variável de ambiente `MSSQL_CONNECTION_STRING`
+2. Variável de ambiente `MSSQL_ENV_FILE` apontando para um arquivo `.env`
+3. 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"
+      }
+    }
+  }
+}
+```
+
+## 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 |
+
+## Licença
+
+MIT

sqlserver_mcp_tools-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sqlserver-mcp-tools"
+version = "0.1.0"
+description = "Servidor MCP (Model Context Protocol) para SQL Server com controle de permissões e modo somente-leitura"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "hlgurgel" },
+]
+keywords = ["mcp", "model-context-protocol", "sql-server", "sqlserver", "mcp-server", "pyodbc", "sql"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp>=1.0.0,<2.0",
+    "pyodbc>=5.0.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.urls]
+Repository = "https://github.com/hlgurgel/mcp-sqlserver"
+Issues = "https://github.com/hlgurgel/mcp-sqlserver/issues"
+
+[project.scripts]
+mcp-sqlserver = "mcp_sqlserver.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

sqlserver_mcp_tools-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sqlserver_mcp_tools-0.1.0/src/mcp_sqlserver/connection.py

@@ -0,0 +1,146 @@
+import os
+from pathlib import Path
+import pyodbc
+from dotenv import load_dotenv
+
+_RAIZ_MCP = Path(__file__).resolve().parent.parent.parent
+
+# Se MSSQL_ENV_FILE estiver definida, carrega o arquivo indicado
+_env_explicito = os.getenv("MSSQL_ENV_FILE", "")
+if _env_explicito:
+    _caminho_explicito = Path(_env_explicito)
+    if _caminho_explicito.exists():
+        load_dotenv(_caminho_explicito, override=True)
+
+# Caminhos automaticos (CWD e raiz do MCP)
+_caminhos_env = [
+    _RAIZ_MCP / ".env",          # menor prioridade (fallback)
+    Path.cwd() / ".." / ".env",  # prioridade media
+    Path.cwd() / ".env",         # maior prioridade (CWD)
+]
+for _caminho in _caminhos_env:
+    if _caminho.exists():
+        load_dotenv(_caminho, override=True)
+
+_CONNECTION_STRING = os.getenv("MSSQL_CONNECTION_STRING", "")
+_CONNECTION = None
+
+
+def get_connection_string() -> str:
+    if not _CONNECTION_STRING:
+        raise ValueError(
+            "MSSQL_CONNECTION_STRING nao definida. "
+            "Configure a variavel de ambiente ou crie um arquivo .env "
+            "baseado no .env.example."
+        )
+    return _CONNECTION_STRING
+
+
+def connection_string_configurada() -> bool:
+    """Indica se a string de conexao esta configurada, sem levantar excecao."""
+    return bool(_CONNECTION_STRING)
+
+
+_PADROES_ERRO_DRIVER = [
+    "can't open lib",
+    "file not found",
+    "data source name not found",
+    "no default driver",
+    "im002",
+    "sqlallochandle",
+]
+
+
+def _eh_erro_driver_odbc(mensagem: str) -> bool:
+    m = mensagem.lower()
+    return any(padrao in m for padrao in _PADROES_ERRO_DRIVER)
+
+
+def conectar_pyodbc(conn_str: str, timeout: int = None):
+    """Abre uma conexao pyodbc, traduzindo erro de driver ODBC ausente em
+    uma mensagem clara para o usuario/LLM."""
+    try:
+        if timeout is None:
+            return pyodbc.connect(conn_str)
+        return pyodbc.connect(conn_str, timeout=timeout)
+    except Exception as e:
+        if _eh_erro_driver_odbc(str(e)):
+            raise RuntimeError(
+                "DRIVER ODBC NAO ENCONTRADO: instale o 'ODBC Driver 18 for SQL Server' "
+                "e reinicie o servidor (macOS: brew install msodbcsql18). "
+                "Erro original: " + str(e)
+            ) from e
+        raise
+
+
+def get_connection():
+    global _CONNECTION
+    conn_str = get_connection_string()
+    if _CONNECTION is not None:
+        try:
+            cursor = _CONNECTION.cursor()
+            cursor.execute("SELECT 1")
+            cursor.close()
+            return _CONNECTION
+        except Exception:
+            try:
+                _CONNECTION.close()
+            except Exception:
+                pass
+            _CONNECTION = None
+    if _CONNECTION is None:
+        _CONNECTION = conectar_pyodbc(conn_str)
+        _CONNECTION.autocommit = False
+        cursor = _CONNECTION.cursor()
+        cursor.execute("SET XACT_ABORT ON")
+        cursor.close()
+    return _CONNECTION
+
+
+def close_connection():
+    global _CONNECTION
+    if _CONNECTION is not None:
+        _CONNECTION.close()
+        _CONNECTION = None
+
+
+_PERMISSAO_ESCRITA_CACHE = None
+
+
+def usuario_tem_permissao_escrita() -> bool:
+    """Detecta se o usuario da conexao tem permissao de escrita no SQL Server.
+
+    Verifica roles de escrita no nivel do servidor (sysadmin) e no banco
+    padrao da conexao (db_owner, db_datawriter, db_ddladmin).
+
+    Fail-safe: se a deteccao falhar por qualquer motivo (banco inacessivel,
+    timeout, sem permissao ate para consultar roles), assume somente leitura
+    (retorna False), nunca expondo ferramentas de escrita por engano.
+
+    O resultado e cacheado na primeira chamada.
+    """
+    global _PERMISSAO_ESCRITA_CACHE
+    if _PERMISSAO_ESCRITA_CACHE is not None:
+        return _PERMISSAO_ESCRITA_CACHE
+
+    _PERMISSAO_ESCRITA_CACHE = False
+    try:
+        conn = get_connection()
+        cursor = conn.cursor()
+        try:
+            cursor.execute(
+                "SELECT "
+                "CAST(IS_SRVROLEMEMBER('sysadmin') AS BIT), "
+                "CAST(IS_MEMBER('db_owner') AS BIT), "
+                "CAST(IS_MEMBER('db_datawriter') AS BIT), "
+                "CAST(IS_MEMBER('db_ddladmin') AS BIT)"
+            )
+            row = cursor.fetchone()
+            if row:
+                _PERMISSAO_ESCRITA_CACHE = any(bool(v) for v in row)
+        finally:
+            cursor.close()
+    except Exception:
+        _PERMISSAO_ESCRITA_CACHE = False
+
+    return _PERMISSAO_ESCRITA_CACHE