MSSQL

Interaja com bancos de dados do Microsoft SQL Server para executar consultas e analisar dados de negócios.

GitHub
39
Experimente este MCPPatrocinado

Documentação

Servidor MCP MSSQL

English | 中文

Visão Geral

O Servidor MCP MSSQL fornece recursos de interação com banco de dados e inteligência de negócios. Este servidor permite executar consultas SQL, analisar dados de negócios e gerar memorandos de insights de negócios automaticamente.
Consulte o SQLite do site oficial para modificações e adaptação ao MSSQL.

Construído sobre o SDK oficial do MCP Python (FastMCP), suportando a especificação MCP 2025-06-18: saída de ferramentas estruturada (structuredContent), anotações de ferramentas, modelos de recursos e confirmação de escrita baseada em elicitação.

Destaques:

  • Multi-banco de dados — monte conexões de dev/staging/prod em um único servidor; cada ferramenta aceita um parâmetro opcional database, cada conexão com suas próprias configurações de readonly / query_timeout / max_rows / confirm_writes
  • Procedimentos armazenados — liste assinaturas e execute procedimentos com coleta completa de múltiplos conjuntos de resultados
  • Modelos de recursos — schema://{database}/{schema}/{table} fornece estruturas de tabelas sob demanda sem consumir tokens de esquema de ferramentas a cada turno
  • Salvaguardas de segurança — lista de permissões SQL, modo somente leitura, limites de linhas, timeouts de consulta, confirmação opcional por elicitação antes de escritas

Componentes

  • read_query
    • Executa consultas SELECT / WITH com saída estruturada (colunas / linhas / contagem_de_linhas / truncado), limitado por max_rows
  • write_query
    • Executa consultas INSERT, UPDATE, DELETE ou MERGE, retorna a contagem de linhas afetadas
  • create_table
    • Cria novas tabelas no banco de dados
  • list_tables
    • Obtém uma lista de todas as tabelas no banco de dados (esquema + nome da tabela)
  • list_views
    • Obtém uma lista de todas as views no banco de dados
  • describe_table
    • Visualiza o esquema completo de uma tabela específica (tipo, anulável, padrão, chave primária, identidade, chaves estrangeiras, índices)
  • list_databases
    • Lista conexões de banco de dados configuradas (nome, somente_leitura, é_padrão)
  • list_procedures
    • Lista procedimentos armazenados com assinaturas de parâmetros
  • execute_procedure
    • Executa um procedimento armazenado (suporta múltiplos conjuntos de resultados)
  • append_insight
    • Adiciona novos insights de negócios ao recurso de memorando

Recursos

  • memo://insights — um memorando vivo de insights de negócios, atualizado em tempo real via append_insight
  • schema://{schema}/{table} — estrutura de tabelas do banco de dados padrão (JSON: colunas / PK / identidade / FKs / índices)
  • schema://{database}/{schema}/{table} — estrutura de tabelas de uma conexão de banco de dados nomeada

Os modelos de recursos são buscados sob demanda: ao contrário dos esquemas de ferramentas, eles não são reenviados ao LLM a cada turno, o que mantém conversas longas enxutas.

Segurança

Todo SQL passa por validação estática antes da execução:

  • read_query aceita apenas uma única instrução SELECT / WITH e rejeita qualquer palavra-chave de escrita ou EXEC (bloqueia, por exemplo, WITH c AS (...) DELETE FROM t)

  • write_query usa uma lista de permissões (apenas INSERT / UPDATE / DELETE / MERGE); EXEC, DROP, TRUNCATE, ALTER são rejeitados

  • Lotes de múltiplas instruções (separados por ;) são rejeitados

  • trusted_connection: true alterna para autenticação integrada do Windows (a string de conexão usa Trusted_Connection=yes, sem necessidade de usuário/senha); false mantém o login da conta SQL configurada

  • readonly: true desativa todas as operações de escrita, incluindo procedimentos armazenados (eles são caixas-pretas que podem escrever)

  • Nomes de procedimentos armazenados são estritamente validados como 1–3 partes de identificador separadas por pontos antes de serem incorporados em {CALL ...}

  • Resultados são truncados em max_rows linhas; consultas são abortadas após query_timeout segundos

  • Com confirm_writes: true, todas as operações que alteram estado (escritas write_query, create_table, execute_procedure) primeiro pedem confirmação ao usuário via elicitação MCP

    ⚠️ Limitação importante: a confirmação depende do cliente implementar o protocolo de Elicitação MCP. Clientes sem suporte a elicitação (ex.: TraeWork / Cursor ...) pulam a confirmação e executam escritas diretamente — o que significa que confirm_writes: true não oferece proteção nesses clientes (um aviso de pulo é registrado no servidor). Para proteção confiável de escrita em qualquer cliente, use readonly: true (bloqueia todas as escritas independentemente das capacidades do cliente)

  • Comentários e literais de string são removidos antes da validação, então não podem ser usados para contornar verificações

Demonstração

A tabela do banco de dados é a seguinte. Os nomes das colunas não são padronizados, e a IA fará a correspondência por conta própria. Erros durante a execução do SQL serão autocorrigidos.

Table

A seguir está a demonstração.

Demo

Ambiente operacional

  • Python 3.10+
  • Packages
    • pyodbc>=4.0.39
    • pydantic>=2.0.0
    • mcp>=1.9.0,<2.0.0
  • ODBC Driver 17 / 18 for SQL Server

Uso

Instalar pacotes

A partir do código-fonte:

git clone <this repo>
CD /d ~/mssql-mcp  
pip install -r requirements.txt

Ou como pacote (pip >= 21.3):

pip install .

Configuração

Crie config.json. Formato de banco único:

{
    "database": {
        "driver": "ODBC Driver 17 for SQL Server",
        "server": "server ip",
        "database": "db name",
        "username": "username",
        "password": "password",
        "trusted_connection": false,
        "readonly": false,
        "query_timeout": 30,
        "max_rows": 200,
        "confirm_writes": false
    },
    "server": {
        "name": "mssql-manager",
        "version": "0.2.0"
    }
}

Formato multi-banco (recomendado — cada conexão tem configurações independentes, ex.: prod permanece somente leitura):

{
    "databases": {
        "default": { "server": "localhost", "database": "dev_db", "...": "..." },
        "prod":    { "server": "10.0.0.5", "database": "prod_db", "readonly": true, "...": "..." }
    },
    "default_database": "default",
    "server": { "name": "mssql-manager", "version": "0.2.0" }
}

Nomes de conexão e a conexão padrão: as chaves em databases são os nomes das conexões — o LLM passa uma delas como o parâmetro database para alternar conexões. As chaves são arbitrárias (você não precisa chamar uma delas de default). default_database decide qual conexão é usada quando database não é passado, resolvido nesta ordem:

  1. Se default_database: "xxx" estiver explicitamente definido, use a conexão nomeada xxx
  2. Caso contrário, se uma conexão nomeada default existir, use-a
  3. Caso contrário, use a primeira conexão no dicionário

Recomendado: defina explicitamente default_database e também mantenha uma conexão literalmente nomeada default como rede de segurança — assim, adicionar novas conexões (que podem acabar primeiro na ordem de iteração) não mudará silenciosamente o padrão.

Ordem de busca do arquivo de configuração: variável de ambiente MSSQL_MCP_CONFIG → config.json ao lado de server.py → config.json no diretório de trabalho.

Campos opcionais (por conexão):

CampoPadrãoDescrição
readonlyfalseModo somente leitura: bloqueia todas as operações de escrita (incl. procedimentos)
query_timeout30Timeout de consulta em segundos
max_rows200Máximo de linhas por conjunto de resultados; linhas extras são truncadas
confirm_writesfalsePedir confirmação do usuário (elicitação) antes de todas as operações que alteram estado (escritas / CREATE TABLE / procedimentos); requer suporte a Elicitação do cliente — clientes sem suporte (ex.: TraeWork / Cursor) executam diretamente; para proteção rígida use readonly
encrypt(nenhum)Criptografia ODBC, para Driver 18 (true / false)
trust_server_certificatefalseConfiar em certificados autoassinados, útil com Driver 18

Variáveis de ambiente:

VariávelPadrãoDescrição
MSSQL_MCP_CONFIG(nenhum)Caminho para um arquivo de configuração alternativo
MSSQL_MCP_LOG_LEVELINFONível de log (DEBUG / INFO / WARNING / ERROR)

Configuração do Cliente (Claude Desktop / Cursor / Windsurf, etc.)

Clientes stdio convencionais (Claude Desktop, Cursor, Windsurf, Cline, etc.) compartilham o mesmo formato JSON mcpServers. Tome o Claude Desktop como exemplo — para outros clientes, adicione a mesma entrada ao arquivo de configuração MCP deles:

# add to claude_desktop_config.json. Note：use your path  
{
    "mcpServers": {
        "mssql": {
            "command": "python",
            "args": [
                # your path，e.g.："C:\\mssql-mcp\\src\\server.py"
                "~/server.py"
            ]
        }
    }
}

Se instalado como pacote, o comando pode ser simplesmente mssql-mcp (sem argumentos necessários).

MCP Inspector

# Note：use your path  
npx -y @modelcontextprotocol/inspector python C:\\mssql-mcp\\src\\server.py

Executar testes

pip install pytest
python -m pytest tests -q
  • tests/test_validation.py — validação de SQL / nomes de procedimentos (sem necessidade de banco de dados)
  • tests/test_config.py — análise de configuração: compatibilidade legada de banco único, multi-banco, casos de erro (sem necessidade de banco de dados)
  • tests/test_integration.py — ponta a ponta contra o banco de dados em src/config.json (escritas tocam apenas objetos de teste dedicados mcp_upgrade_*, limpos automaticamente)

Estrutura do Projeto

mssql-mcp
├── .git
├── .gitignore
├── LICENSE
├── README.md
├── README_en.md
├── README_zh.md
├── imgs
│   ├── table.png
│   └── demo.gif
├── pyproject.toml        (packaging: src/ is installed as the mssql_mcp package)
├── requirements.txt
├── src
│   ├── __init__.py
│   ├── config.json      (gitignored, local database config)
│   └── server.py
└── tests
    ├── test_validation.py
    ├── test_config.py
    └── test_integration.py

Licença

Licença MIT