SQL Server MCP Server (Python)

Model Context Protocol (MCP)를 Python으로 구현한 서버로, Microsoft SQL Server 데이터베이스와의 통합을 제공합니다.

이 서버는 스키마 검사와 CRUD(Create, Read, Update, Delete) 작업을 위한 완전한 도구를 제공하며, 빠른 데이터 및 스키마 조회를 위한 MCP 리소스도 제공합니다.

사용 가능한 도구

스키마 및 검사

• list_schemas(): 데이터베이스에 있는 모든 사용자 스키마를 나열합니다.

• list_tables(schema_name=None): 데이터베이스의 테이블과 뷰를 나열하며 스키마별 필터링 옵션을 제공합니다.

• get_table_schema(table_name, schema_name="dbo"): 테이블의 구조적 세부 정보(열, 데이터 형식, 기본 키, 외래 키, IDENTITY)를 반환합니다.

• get_database_schema(schema_name=None, table_name=None): 전체 데이터베이스 스키마 또는 필터링된 스키마를 반환합니다.

CRUD 작업

• read_records(table_name, schema_name="dbo", columns=None, where_clause=None, params=None, order_by=None, limit=100, offset=0): 사용자 지정 열, 매개변수화된 WHERE 필터, 정렬 및 페이징을 사용하여 테이블의 레코드를 조회합니다.

• read_query(sql_query, params=None): T-SQL에서 사용자 지정 SELECT 쿼리를 실행하며 위치 매개변수(?)를 지원합니다.

• insert_record(table_name, data, schema_name="dbo"): 테이블에 단일 레코드(키/값 사전)를 삽입합니다.

• bulk_insert_records(table_name, records, schema_name="dbo"): 트랜잭션 내에서 여러 레코드를 일괄 삽입합니다.

• update_records(table_name, data, where_clause, where_params=None, schema_name="dbo"): 매개변수화된 WHERE 절과 일치하는 레코드를 업데이트합니다.

• delete_records(table_name, where_clause, params=None, schema_name="dbo"): WHERE 절과 일치하는 레코드를 안전하게 삭제합니다.

• execute_sql(sql_statement, params=None): 임의의 DDL/DML 명령(CREATE, ALTER, DROP, INSERT, UPDATE, DELETE)을 실행합니다.

Related MCP server: SQL Server MCP

MCP 리소스

• sqlserver://schema: 데이터베이스의 전체 스키마를 JSON 형식으로 반환합니다.

• sqlserver://tables: 사용 가능한 테이블과 뷰 목록을 반환합니다.

설치 및 구성

1. 요구 사항

• Python >= 3.10

• SQL Server 드라이버(pyodbc는 SQL Server ODBC Driver와 함께 사용하며, 순수 Python 연결에는 pymssql을 지원합니다).

2. 환경 구성(.env)

프로젝트 루트에 .env 파일을 만들거나 환경 변수를 설정하세요:

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

3. 설치

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

pip install -e .

MCP 클라이언트 구성

mcp.json 예시 / 클라이언트 구성

{
  "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"
      }
    }
  }
}

🐳 Docker & Makefile

Makefile을 사용하면 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

🧪 테스트

애플리케이션의 단위 테스트를 실행하려면:

pytest