@yuuzu/sql-mcp

npm version

MSSQL, PostgreSQL 및 SQLite 데이터베이스 작업을 위한 Model Context Protocol (MCP) 서버입니다.

설치

# Using bunx (recommended)
bunx @yuuzu/sql-mcp

# Using npx
npx @yuuzu/sql-mcp

기능

다중 데이터베이스 지원: MSSQL, PostgreSQL 및 SQLite (better-sqlite3 사용)
8가지 데이터베이스 작업 도구
세 가지 쿼리 모드: safe, write, full
고급 인증: Windows 인증 (MSSQL), SSL 인증서 (PostgreSQL)

도구

도구	설명
`connect-database`	데이터베이스 서버에 연결
`disconnect`	현재 연결 해제
`connection-status`	연결 상태 및 쿼리 모드 확인
`list-databases`	서버의 모든 데이터베이스 나열
`switch-database`	다른 데이터베이스로 전환
`list-tables`	모든 테이블 및 뷰 나열
`describe-table`	테이블 스키마 세부 정보 가져오기
`execute-query`	SQL 쿼리 실행

쿼리 모드

SQL_MCP_MODE 환경 변수를 통해 쿼리 권한을 제어합니다:

모드	허용되는 작업	설명
`safe` (기본값)	SELECT, WITH, EXPLAIN	읽기 전용, 가장 안전함
`write`	+ INSERT, UPDATE, DELETE	데이터 수정 허용
`full`	+ CREATE, DROP, ALTER, TRUNCATE	전체 액세스, 주의해서 사용

참고: PRAGMA 문(예: PRAGMA table_info(users))은 SQLite에서 일반적으로 사용되는 읽기 전용 메타데이터 쿼리이므로 safe를 포함한 모든 모드에서 허용됩니다.

# Example: Enable write mode
SQL_MCP_MODE=write bunx @yuuzu/sql-mcp

사용 예시

Claude Desktop 구성

claude_desktop_config.json에 추가하세요:

{
    "mcpServers": {
        "sql-mcp": {
            "command": "bunx",
            "args": ["@yuuzu/sql-mcp"],
            "env": {
                "SQL_MCP_MODE": "safe"
            }
        }
    }
}

MSSQL에 연결

{
    "tool": "connect-database",
    "arguments": {
        "engine": "mssql",
        "server": "localhost",
        "port": 1433,
        "user": "sa",
        "password": "your_password",
        "database": "master"
    }
}

PostgreSQL에 연결

{
    "tool": "connect-database",
    "arguments": {
        "engine": "postgres",
        "server": "localhost",
        "port": 5432,
        "user": "postgres",
        "password": "your_password",
        "database": "postgres"
    }
}

Windows 인증으로 연결 (MSSQL)

{
    "tool": "connect-database",
    "arguments": {
        "engine": "mssql",
        "server": "localhost",
        "windowsAuth": true
    }
}

SSL로 연결 (PostgreSQL)

{
    "tool": "connect-database",
    "arguments": {
        "engine": "postgres",
        "server": "your-server.com",
        "user": "postgres",
        "password": "your_password",
        "ssl": {
            "rejectUnauthorized": true,
            "ca": "/path/to/ca-certificate.crt"
        }
    }
}

SQLite에 연결 (파일)

{
    "tool": "connect-database",
    "arguments": {
        "engine": "sqlite",
        "filename": "/absolute/path/to/database.db"
    }
}

SQLite에 연결 (인메모리)

테스트, 데모 또는 일시적인 작업 공간에 유용합니다.

{
    "tool": "connect-database",
    "arguments": {
        "engine": "sqlite",
        "filename": ":memory:"
    }
}

SQLite에 연결 (읽기 전용)

{
    "tool": "connect-database",
    "arguments": {
        "engine": "sqlite",
        "filename": "/absolute/path/to/database.db",
        "readonly": true,
        "fileMustExist": true
    }
}

SQLite 런타임 참고: SQLite 지원은 Node.js가 필요한 better-sqlite3를 사용합니다. bunx를 통해 실행할 때 MSSQL과 PostgreSQL은 정상적으로 작동하지만, SQLite 연결은 npx나 node를 사용하라는 명확한 오류 메시지를 반환합니다.

개발

# Install dependencies
bun install

# Run in development mode
bun run dev

# Run tests
bun test

# Run tests with coverage
bun test --coverage

# Build
bun run build

# Type check
bun run typecheck

릴리스

릴리스는 GitHub Actions를 통해 자동화됩니다. 새 릴리스를 생성하려면:

# Create and push a version tag
git tag v1.0.0
git push origin v1.0.0

이 작업은 다음을 수행합니다:

프로젝트 빌드
출처(provenance)와 함께 npm에 게시
자동 생성된 릴리스 노트를 포함하여 GitHub 릴리스 생성

요구 사항: GitHub 저장소 설정에 NPM_TOKEN 시크릿을 설정하세요.

라이선스

MIT

sql-mcp