MCP SQL 서버 (개발용)

모든 MCP 호환 LLM을 SQL 데이터베이스에 연결하여 다음 작업을 수행할 수 있는 전문가용 MCP 서버입니다:

• 쿼리 (SELECT, WITH, SHOW 등)

• DML (INSERT, UPDATE, DELETE)

• DDL (CREATE, ALTER 및 선택적으로 DROP/TRUNCATE)

이 서버는 개발 지원을 위한 개인용으로 설계되었습니다.

주요 기능

• stdio를 통한 MCP 프로토콜 (MCP 클라이언트와 호환).

• SQLAlchemy를 통한 다중 엔진 연결 (sqlite, postgresql, mysql, mssql 등).

• 일상적인 작업에 초점을 맞춘 MCP 도구:

  • sql_capabilities

  • sql_list_tables

  • sql_describe_table

  • sql_run

  • sql_run_script

• 기본적으로 파괴적인 DDL 차단 (DROP/TRUNCATE 차단됨).

• 행 수 및 스크립트당 문장 수 제한 설정 가능.

설치

python -m venv .venv
source .venv/bin/activate
pip install -e .

설정 (환경 변수)

접두사: MCP_SQL_

• MCP_SQL_DATABASE_URL: SQLAlchemy URL. 기본값: sqlite:///./dev.db

• MCP_SQL_MAX_ROWS: 쿼리당 반환되는 최대 행 수. 기본값: 200

• MCP_SQL_MAX_SCRIPT_STATEMENTS: 스크립트당 최대 문장 수. 기본값: 100

• MCP_SQL_ALLOW_DESTRUCTIVE_DDL: DROP 및 TRUNCATE 허용 여부 (true/false). 기본값: false

예시

export MCP_SQL_DATABASE_URL='postgresql+psycopg://dev_user:dev_pass@localhost:5432/devdb'
export MCP_SQL_MAX_ROWS=500
export MCP_SQL_ALLOW_DESTRUCTIVE_DDL=false

서버 실행

mcp-sql-server

모듈로 실행할 수도 있습니다:

python -m mcp_sql_server.server

Windows에서 더블 클릭으로 시작

간편한 시작을 위해 start_mcp_sql_server.bat 파일이 포함되어 있습니다:

1. .venv가 없으면 자동으로 생성합니다.

2. 종속성을 설치/업데이트합니다.

3. MCP 서버를 실행합니다.

해당 .bat 파일을 더블 클릭하기만 하면 됩니다.

MCP 클라이언트 설정 (일반 예시)

{
  "mcpServers": {
    "sql-dev": {
      "command": "mcp-sql-server",
      "env": {
        "MCP_SQL_DATABASE_URL": "sqlite:///./dev.db",
        "MCP_SQL_MAX_ROWS": "200",
        "MCP_SQL_ALLOW_DESTRUCTIVE_DDL": "false"
      }
    }
  }
}

권장 워크플로우

1. sql_capabilities를 사용하여 활성 설정을 확인합니다.

2. sql_list_tables를 사용하여 스키마를 탐색합니다.

3. sql_describe_table을 사용하여 메타데이터를 검사합니다.

4. sql_run을 사용하여 쿼리나 단일 DML을 실행합니다.

5. sql_run_script를 사용하여 제어된 변경 사항을 일괄 처리합니다.

개발 지원을 위한 모범 사례

• 최소 권한을 가진 데이터베이스 사용자를 사용하세요.

• 로컬 개발 DB 또는 일회용 스냅샷에서 작업하세요.

• 기본적으로 MCP_SQL_ALLOW_DESTRUCTIVE_DDL=false를 유지하세요.

• 구조적 변경 사항은 마이그레이션을 통해 버전 관리하세요.

보안 참고 사항

이 프로젝트는 프로덕션 환경을 위해 강화되지 않았습니다. 로컬 개발 환경에서의 생산성 향상을 목적으로 합니다.

VS Code의 Claude 가이드

전체 설정 및 사용 예시는 README_CLAUDE_VSCODE.md를 확인하세요.