SQL Server MCP Server (Python)

Um servidor Model Context Protocol (MCP) em Python para integração com bancos de dados Microsoft SQL Server.

O servidor disponibiliza ferramentas completas de inspeção de schema e operações CRUD (Create, Read, Update, Delete), além de recursos MCP para consulta rápida de dados e schemas.

Ferramentas Disponíveis (Tools)

Schema & Inspeção

• list_schemas(): Lista todos os schemas de usuário presentes no banco de dados.
• list_tables(schema_name=None): Lista tabelas e views do banco de dados com opção de filtro por schema.
• get_table_schema(table_name, schema_name="dbo"): Retorna detalhes estruturais da tabela (colunas, tipos de dados, chaves primárias, chaves estrangeiras e identidades).
• get_database_schema(schema_name=None, table_name=None): Retorna o schema completo do banco de dados ou filtrado.

Operações CRUD

• read_records(table_name, schema_name="dbo", columns=None, where_clause=None, params=None, order_by=None, limit=100, offset=0): Consulta registros de uma tabela com colunas personalizadas, filtros WHERE parametrizados, ordenação e paginação.
• read_query(sql_query, params=None): Executa uma query SELECT personalizada em T-SQL com suporte a parâmetros posicionais (?).
• insert_record(table_name, data, schema_name="dbo"): Insere um único registro (dicionário chave/valor) em uma tabela.
• bulk_insert_records(table_name, records, schema_name="dbo"): Insere múltiplos registros em lote dentro de uma transação.
• update_records(table_name, data, where_clause, where_params=None, schema_name="dbo"): Atualiza registros correspondentes a uma cláusula WHERE parametrizada.
• delete_records(table_name, where_clause, params=None, schema_name="dbo"): Remove registros correspondentes a uma cláusula WHERE de forma segura.
• execute_sql(sql_statement, params=None): Executa comandos DDL/DML arbitrários (CREATE, ALTER, DROP, INSERT, UPDATE, DELETE).

Recursos MCP (Resources)

• sqlserver://schema: Retorna o schema completo do banco de dados em formato JSON.
• sqlserver://tables: Retorna a lista de tabelas e views disponíveis.

Instalação e Configuração

1. Requisitos

• Python >= 3.10
• Driver SQL Server (Suporta pyodbc com ODBC Driver do SQL Server e pymssql para conexões puras em Python).

2. Configuração do Ambiente (.env)

Crie um arquivo .env na raiz do projeto ou defina as variáveis de ambiente:

SQLSERVER_HOST=localhost
SQLSERVER_PORT=1433
SQLSERVER_DATABASE=MeuBanco
SQLSERVER_USER=sa
SQLSERVER_PASSWORD=SuaSenha123!
SQLSERVER_DRIVER_TYPE=auto
SQLSERVER_TRUST_SERVER_CERTIFICATE=true

Uso com SQL Server Express LocalDB

O servidor possui suporte nativo ao SQL Server LocalDB (com suporte a anexar arquivos .mdf diretamente):

Via variáveis de ambiente (.env):

SQLSERVER_USE_LOCALDB=true
SQLSERVER_LOCALDB_INSTANCE=MSSQLLOCALDB
SQLSERVER_DATABASE=MeuBanco
# Opcional: Caminho para anexar um arquivo .mdf diretamente
# SQLSERVER_ATTACH_DB_FILENAME=C:\Caminho\Para\Banco.mdf

Ou configurando SQLSERVER_HOST=(localdb)\MSSQLLOCALDB.

Via linha de comando:

python -m sql_server_mcp.server --localdb --database MeuBanco
# Ou anexando um arquivo MDF:
python -m sql_server_mcp.server --localdb --attach-db-filename C:\Data\MeuBanco.mdf

3. Instalação

python -m venv .venv
# Windows
.\.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate

pip install -e .

Configuração em Clientes MCP

Exemplo de mcp.json / Configuração de Cliente

{
  "mcpServers": {
    "sql-server": {
      "command": "python",
      "args": [
        "-m",
        "sql_server_mcp.server"
      ],
      "env": {
        "SQLSERVER_HOST": "localhost",
        "SQLSERVER_PORT": "1433",
        "SQLSERVER_DATABASE": "MeuBanco",
        "SQLSERVER_USER": "sa",
        "SQLSERVER_PASSWORD": "SuaSenha123!",
        "SQLSERVER_TRUST_SERVER_CERTIFICATE": "true"
      }
    },
    "sql-server-localdb": {
      "command": "python",
      "args": [
        "-m",
        "sql_server_mcp.server",
        "--localdb",
        "--database", "MeuBanco"
      ]
    }
  }
}

🐳 Docker & Makefile

Você pode usar o Makefile para facilitar a compilação e execução via Docker:

# Compilar a imagem Docker
make build

# Executar o servidor MCP em container utilizando as variáveis do .env
make run

# Rodar os testes unitários dentro do container Docker
make docker-test

# Exibir ajuda dos comandos Makefile
make help

---

🧪 Testes

Para rodar os testes unitários da aplicação:

pytest