MS SQL MCP 서버 1.1

클로드와 같은 AI 비서가 Microsoft SQL Server 데이터베이스를 직접 쿼리하고 탐색할 수 있도록 해주는 사용하기 쉬운 브리지입니다. 코딩 경험은 필요 없습니다!

이 도구는 무슨 역할을 하나요?

이 도구를 사용하면 AI 도우미가 다음을 수행할 수 있습니다.

SQL Server 데이터베이스에서 테이블 검색
테이블 구조(열, 데이터 유형 등) 보기
읽기 전용 SQL 쿼리를 안전하게 실행하세요
자연어 요청에서 SQL 쿼리 생성

🌟 이 도구가 필요한 이유

데이터와 AI 간의 격차 해소

코딩 필요 없음 : 복잡한 통합 코드를 작성하지 않고도 Claude와 다른 AI 도우미가 SQL Server 데이터베이스에 직접 액세스할 수 있도록 합니다.
제어 유지 : 모든 쿼리는 기본적으로 읽기 전용이므로 데이터가 안전하게 유지됩니다.
개인 정보 보호 및 보안 : 데이터베이스 자격 증명은 로컬에 유지되며 외부 서비스로 전송되지 않습니다.

실용적인 이점

수 시간의 수동 작업 절약 : 더 이상 AI와 공유하기 위해 데이터나 쿼리 결과를 복사하여 붙여넣을 필요가 없습니다.
심층 분석 : AI는 전체 데이터베이스 스키마를 탐색하고 여러 테이블에 대한 통찰력을 제공할 수 있습니다.
자연어 인터페이스 : 일반 영어로 데이터에 대한 질문을 하세요
컨텍스트 제한 문제 종료 : 일반 AI 컨텍스트 창을 초과하는 대용량 데이터 세트에 액세스

완벽한

자격 증명을 공유하지 않고도 SQL 데이터를 해석하는 데 AI의 도움이 필요한 데이터 분석가
자연스러운 대화를 통해 데이터베이스 구조를 빠르게 탐색할 수 있는 방법을 찾는 개발자
SQL 전문 지식 없이 통찰력이 필요한 비즈니스 분석가
AI 도구에 대한 통제된 액세스를 제공하려는 데이터베이스 관리자

🚀 빠른 시작 가이드

1단계: 필수 구성 요소 설치

Node.js (버전 14 이상)를 설치하세요
Microsoft SQL Server 데이터베이스(온프레미스 또는 Azure)에 액세스할 수 있음

2단계: 복제 및 설정

지엑스피1

3단계: 데이터베이스 연결 구성

데이터베이스 자격 증명으로 .env 파일을 편집합니다.

DB_USER=your_username
DB_PASSWORD=your_password
DB_SERVER=your_server_name_or_ip
DB_DATABASE=your_database_name
PORT=3333
TRANSPORT=stdio
SERVER_URL=http://localhost:3333
DEBUG=false                     # Set to 'true' for detailed logging (helpful for troubleshooting)
QUERY_RESULTS_PATH=/path/to/query_results  # Directory where query results will be saved as JSON files

4단계: 서버 시작

# Start with default stdio transport
npm start

# OR start with HTTP/SSE transport for network access
npm run start:sse

5단계: 시도해 보세요!

# Run the interactive client
npm run client

📊 사용 사례 예시

SQL을 작성하지 않고 데이터베이스 구조 탐색
mcp_SQL_mcp_discover_database()
특정 테이블에 대한 자세한 정보를 얻으세요
mcp_SQL_mcp_table_details({ tableName: "Customers" })
안전한 쿼리 실행
mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Customers", returnResults: true })
이름 패턴으로 테이블 찾기
mcp_SQL_mcp_discover_tables({ namePattern: "%user%" })
페이지 매김을 사용하여 대규모 결과 집합을 탐색하세요.
// First page mcp_SQL_mcp_execute_query({ sql: "SELECT * FROM Users ORDER BY Username OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY", returnResults: true }) // Next page mcp_SQL_mcp_execute_query({ sql: "SELECT * FROM Users ORDER BY Username OFFSET 10 ROWS FETCH NEXT 10 ROWS ONLY", returnResults: true })
최적의 성능을 위한 커서 기반 페이지 매김
// First page mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Users ORDER BY Username", returnResults: true }) // Next page using the last value as cursor mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Users WHERE Username > 'last_username' ORDER BY Username", returnResults: true })
자연어로 질문하세요
"Show me the top 5 customers with the most orders in the last month"

💡 실제 세계 응용 프로그램

비즈니스 인텔리전스를 위해

판매 실적 분석 : "지난 1년간의 월별 판매 추세를 보여주시고 지역별로 성과가 가장 좋은 제품을 찾아주세요."
고객 세분화 : 구매 빈도, 평균 주문 가치, 지리적 위치별로 고객 기반을 분석합니다.
재무 보고 : "올해와 작년을 비교하는 분기별 손익 보고서를 작성하세요."

데이터베이스 관리를 위해

스키마 최적화 : "쿼리 성능 데이터를 조사하여 인덱스가 누락된 테이블을 식별하는 데 도움을 주세요."
데이터 품질 감사 : "정보가 불완전하거나 잘못된 값이 있는 모든 고객 기록을 찾습니다."
사용 분석 : "어떤 테이블에 가장 자주 액세스하는지, 어떤 쿼리가 가장 많은 리소스를 사용하는지 보여주세요."

개발을 위해

API 탐색 : "API를 구축하고 있습니다. 적절한 엔드포인트를 설계하기 위해 데이터베이스 스키마를 분석하는 데 도움을 주세요."
쿼리 최적화 : "이 복잡한 쿼리를 검토하고 성능 개선 방안을 제안해 주세요."
데이터베이스 문서화 : "관계에 대한 설명을 포함하여 데이터베이스 구조에 대한 포괄적인 문서를 작성합니다."

🖥️ 대화형 클라이언트 기능

번들된 클라이언트는 간편한 메뉴 기반 인터페이스를 제공합니다.

사용 가능한 리소스 나열 - 사용 가능한 정보 확인
사용 가능한 도구 나열 - 수행할 수 있는 작업 확인
SQL 쿼리 실행 - 읽기 전용 SQL 쿼리 실행
테이블 세부 정보 가져오기 - 모든 테이블의 구조 보기
데이터베이스 스키마 읽기 - 모든 테이블과 해당 관계 보기
SQL 쿼리 생성 - 자연어를 SQL로 변환

🧠 효과적인 프롬프팅 및 도구 사용 가이드

이 MCP 서버를 통해 Claude 또는 다른 AI 비서와 작업할 때, 요청을 표현하는 방식은 결과에 상당한 영향을 미칩니다. AI가 데이터베이스 도구를 효과적으로 사용할 수 있도록 돕는 방법은 다음과 같습니다.

기본 도구 호출 형식

AI에게 이 도구를 사용하도록 지시할 때 다음 구조를 따르세요.

Can you use the SQL MCP tools to [your goal]?

For example:
- Check what tables exist in my database
- Query the Customers table and show me the first 10 records
- Find all orders from the past month

필수 명령 및 구문

주요 도구와 올바른 구문은 다음과 같습니다.

// Discover the database structure
mcp_SQL_mcp_discover_database()

// Get detailed information about a specific table
mcp_SQL_mcp_table_details({ tableName: "YourTableName" })

// Execute a query and return results
mcp_SQL_mcp_execute_query({ 
  sql: "SELECT * FROM YourTable WHERE Condition", 
  returnResults: true 
})

// Find tables by name pattern
mcp_SQL_mcp_discover_tables({ namePattern: "%pattern%" })

// Access saved query results (for large result sets)
mcp_SQL_mcp_get_query_results({ uuid: "provided-uuid-here" })

각 도구를 사용하는 경우:

데이터베이스 검색 : AI가 데이터베이스 구조에 익숙하지 않을 때 시작하세요.
테이블 세부 정보 : 쿼리를 작성하기 전에 특정 테이블에 초점을 맞출 때 사용합니다.
쿼리 실행 : 실제 데이터를 검색하거나 분석해야 할 때.
패턴으로 테이블 검색 : 특정 도메인과 관련된 테이블을 찾을 때.

효과적인 프롬프트 패턴

단계별 워크플로

복잡한 작업의 경우 AI를 일련의 단계로 안내합니다.

I'd like to analyze our sales data. Please:
First use mcp_SQL_mcp_discover_tables to find tables related to sales
Use mcp_SQL_mcp_table_details to examine the structure of relevant tables
Create a query with mcp_SQL_mcp_execute_query that shows monthly sales by product category

먼저 구조를 만들고, 그 다음에 쿼리를 작성하세요

First, discover what tables exist in my database. Then, look at the structure
of the Customers table. Finally, show me the top 10 customers by total purchase amount.

설명을 요청하세요

Query the top 5 underperforming products based on sales vs. forecasts,
and explain your approach to writing this query.

SQL Server 언어 노트

AI에게 SQL Server의 특정 구문을 상기시켜줍니다.

Please use SQL Server syntax for pagination:
- For offset/fetch: "OFFSET 10 ROWS FETCH NEXT 10 ROWS ONLY"
- For cursor-based: "WHERE ID > last_id ORDER BY ID"

도구 사용 수정

AI가 잘못된 구문을 사용하는 경우 다음과 같은 방법으로 도움을 줄 수 있습니다.

That's not quite right. Please use this format for the tool call:
mcp_SQL_mcp_execute_query({ 
  sql: "SELECT * FROM Customers WHERE Region = 'West'",
  returnResults: true
})

프롬프트를 통한 문제 해결

AI가 데이터베이스 작업에 어려움을 겪는 경우 다음 방법을 시도해 보세요.

테이블에 대해 더 구체적으로 설명하세요. "해당 쿼리를 작성하기 전에 CustomerOrders 테이블이 있는지, 어떤 열이 있는지 확인하세요."
복잡한 작업을 단계별로 나누어 보세요. "단계별로 접근해 보겠습니다. 먼저 Products 테이블 구조를 살펴보세요. 그런 다음 Orders 테이블을 확인하세요..."
중간 결과를 요청하세요. "더 복잡한 분석을 시도하기 전에 데이터 형식을 확인할 수 있도록 먼저 해당 테이블에 간단한 쿼리를 실행하세요."
쿼리 설명 요청: "이 쿼리를 작성한 후 각 부분이 무엇을 하는지 설명하여 내가 원하는 작업을 수행하는지 확인할 수 있습니다."

🔎 고급 쿼리 기능

테이블 발견 및 탐색

MCP 서버는 데이터베이스 구조를 탐색하기 위한 강력한 도구를 제공합니다.

패턴 기반 테이블 검색 : 특정 패턴과 일치하는 테이블 찾기
mcp_SQL_mcp_discover_tables({ namePattern: "%order%" })
스키마 개요 : 스키마별로 테이블의 상위 수준 보기
mcp_SQL_mcp_execute_query({ sql: "SELECT TABLE_SCHEMA, COUNT(*) AS TableCount FROM INFORMATION_SCHEMA.TABLES GROUP BY TABLE_SCHEMA" })
열 탐색 : 모든 테이블의 열 메타데이터를 조사합니다.
mcp_SQL_mcp_table_details({ tableName: "dbo.Users" })

페이지 매김 기술

서버는 대규모 데이터 세트를 처리하기 위해 다양한 페이지 매김 방법을 지원합니다.

오프셋/페치 페이징 : OFFSET 및 FETCH를 사용한 표준 SQL 페이징
mcp_SQL_mcp_execute_query({ sql: "SELECT * FROM Users ORDER BY Username OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY" })
커서 기반 페이징 : 대용량 데이터 세트에 더 효율적
// Get first page mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Users ORDER BY Username" }) // Get next page using last value as cursor mcp_SQL_mcp_execute_query({ sql: "SELECT TOP 10 * FROM Users WHERE Username > 'last_username' ORDER BY Username" })
데이터로 계산 : 페이지가 나뉜 데이터와 함께 총 개수 검색
mcp_SQL_mcp_execute_query({ sql: "WITH TotalCount AS (SELECT COUNT(*) AS Total FROM Users) SELECT TOP 10 u.*, t.Total FROM Users u CROSS JOIN TotalCount t ORDER BY Username" })

복잡한 조인 및 관계

조인 작업을 사용하여 테이블 간의 관계를 살펴보세요.

mcp_SQL_mcp_execute_query({ 
  sql: "SELECT u.Username, u.Email, r.RoleName FROM Users u JOIN UserRoles ur ON u.Username = ur.Username JOIN Roles r ON ur.RoleId = r.RoleId ORDER BY u.Username"
})

분석 쿼리

집계 및 분석 쿼리를 실행하여 통찰력을 얻으세요.

mcp_SQL_mcp_execute_query({ 
  sql: "SELECT UserType, COUNT(*) AS UserCount, SUM(CASE WHEN IsActive = 1 THEN 1 ELSE 0 END) AS ActiveUsers FROM Users GROUP BY UserType"
})

SQL Server 기능 사용

MCP 서버는 SQL Server 관련 기능을 지원합니다.

공통 테이블 표현식(CTE)
윈도우 함수
JSON 작업
계층적 쿼리
전체 텍스트 검색 (데이터베이스에 구성된 경우)

🔗 통합 옵션

Claude 데스크톱 통합

몇 가지 간단한 단계로 이 도구를 Claude Desktop에 직접 연결하세요.

anthropic.com 에서 Claude Desktop을 설치하세요
Claude의 구성 파일을 편집합니다.
- 위치: ~/Library/Application Support/Claude/claude_desktop_config.json
- 다음 구성을 추가합니다.

{
    "mcpServers": {
        "mssql": {
            "command": "node",
            "args": [
                "/FULL/PATH/TO/mssql-mcp-server/server.mjs"
            ]
        }
    }
}

/FULL/PATH/TO/ 이 저장소를 복제한 실제 경로로 바꾸세요.
Claude Desktop을 다시 시작하세요
Claude Desktop에서 도구 아이콘을 찾아보세요. 이제 데이터베이스 명령을 직접 사용할 수 있습니다!

커서 IDE에 연결하기

커서는 고급 데이터베이스 상호작용을 위해 이 도구를 활용할 수 있는 AI 기반 코드 편집기입니다. 설정 방법은 다음과 같습니다.

커서 설정

Cursor IDE를 엽니다( cursor.sh 가 없으면 여기에서 다운로드하세요)
HTTP/SSE 전송을 사용하여 MS SQL MCP 서버를 시작합니다.
npm run start:sse
Cursor에서 새 작업 공간을 만들거나 기존 프로젝트를 엽니다.
커서 설정 입력
MCP를 클릭하세요
새로운 MCP 서버 추가
MCP 서버 이름을 지정하고 유형을 선택하세요: sse
서버 URL을 localhost:3333/sse(또는 실행 중인 포트)로 입력하세요.

커서에서 데이터베이스 명령 사용

연결되면 Cursor의 AI 채팅에서 MCP 명령을 직접 사용할 수 있습니다.

커서에서 Claude에게 데이터베이스를 탐색해 달라고 요청하세요.
Can you show me the tables in my database?
특정 쿼리를 실행합니다.
Query the top 10 records from the Customers table
복잡한 쿼리를 생성하고 실행합니다.
Find all orders from the last month with a value over $1000

커서 연결 문제 해결

MS SQL MCP 서버가 HTTP/SSE 전송으로 실행 중인지 확인하세요.
포트가 올바르고 .env 파일에 있는 내용과 일치하는지 확인하세요.
방화벽이 연결을 차단하지 않는지 확인하세요.
다른 IP/호스트 이름을 사용하는 경우 .env 파일에서 SERVER_URL을 업데이트하세요.

🔄 운송 방법 설명

옵션 1: stdio 전송(기본값)

가장 적합한 용도: Claude Desktop 또는 번들 클라이언트와 직접 사용

npm start

옵션 2: HTTP/SSE 전송

가장 적합한 용도: 네트워크 액세스 또는 웹 애플리케이션과 함께 사용하는 경우

npm run start:sse

🛡️ 보안 기능

기본적으로 읽기 전용 : 데이터 수정 위험 없음
개인 자격 증명 : 데이터베이스 연결 세부 정보는 .env 파일에 보관됩니다.
SQL 주입 보호 : SQL 쿼리에 대한 내장 검증

🔎 신규 사용자를 위한 문제 해결

"데이터베이스에 연결할 수 없습니다"

올바른 데이터베이스 자격 증명을 확인하려면 .env 파일을 확인하세요.
SQL Server가 실행 중이고 연결을 수락하는지 확인하세요.
Azure SQL의 경우 방화벽 설정에서 IP가 허용되는지 확인하세요.

"모듈을 찾을 수 없습니다" 오류

모든 종속성이 설치되었는지 확인하려면 npm install 다시 실행하세요.
Node.js 버전 14 이상을 사용하고 있는지 확인하세요.

"전송 오류" 또는 "연결이 거부되었습니다"

HTTP/SSE 전송의 경우 .env의 PORT가 사용 가능한지 확인하세요.
방화벽이 연결을 차단하지 않는지 확인하세요.

Claude Desktop에 연결할 수 없습니다.

claude_desktop_config.json 에서 경로를 다시 확인하세요.
상대 경로가 아닌 절대 경로를 사용하고 있는지 확인하세요.
변경 사항을 적용한 후 Claude Desktop을 완전히 다시 시작하세요.

📚 SQL Server 기본 사항 이해

SQL Server를 처음 사용하는 분들을 위해 몇 가지 주요 개념을 알려드리겠습니다.

표 : 행과 열로 데이터를 저장합니다.
스키마 : 테이블의 논리적 그룹(폴더 등)
쿼리 : 데이터를 검색하거나 분석하는 명령
뷰 : 쉽게 액세스할 수 있도록 미리 정의된 쿼리가 저장됨

이 도구를 사용하면 SQL 전문가가 아니어도 이 모든 것을 탐색할 수 있습니다!

🏗️ 아키텍처 및 핵심 모듈

MS SQL MCP 서버는 유지 관리성과 확장성에 대한 우려를 분리하는 모듈식 아키텍처로 구축되었습니다.

핵심 모듈

`database.mjs` - 데이터베이스 연결

SQL Server 연결 풀링을 관리합니다.
재시도 논리 및 오류 처리를 통해 쿼리 실행을 제공합니다.
데이터베이스 연결, 트랜잭션 및 구성을 처리합니다.
SQL 및 포맷 오류를 정리하기 위한 유틸리티가 포함되어 있습니다.

`tools.mjs` - 도구 등록

모든 데이터베이스 도구를 MCP 서버에 등록합니다.
도구 검증 및 매개변수 검사를 구현합니다.
SQL 쿼리, 테이블 탐색 및 데이터베이스 검색을 위한 핵심 기능을 제공합니다.
데이터베이스 작업에 대한 지도 도구 호출

`resources.mjs` - 데이터베이스 리소스

리소스 엔드포인트를 통해 데이터베이스 메타데이터를 노출합니다.
스키마 정보, 테이블 목록 및 프로시저 문서를 제공합니다.
AI 사용을 위한 데이터베이스 구조 정보 형식
데이터베이스 탐색을 위한 검색 유틸리티가 포함되어 있습니다.

`pagination.mjs` - 결과 탐색

대규모 결과 집합에 대한 커서 기반 페이지 매김을 구현합니다.
다음/이전 페이지 커서를 생성하기 위한 유틸리티를 제공합니다.
페이지 매김을 지원하기 위해 SQL 쿼리를 변환합니다.
SQL Server의 OFFSET/FETCH 페이지 매김 구문을 처리합니다.

`errors.mjs` - 오류 처리

다양한 실패 시나리오에 대한 사용자 정의 오류 유형을 정의합니다.
JSON-RPC 오류 포맷을 구현합니다.
사람이 읽을 수 있는 오류 메시지를 제공합니다.
전역 오류 처리를 위한 미들웨어가 포함되어 있습니다.

`logger.mjs` - 로깅 시스템

여러 전송을 사용하여 Winston 로깅을 구성합니다.
컨텍스트 인식 요청 로깅 제공
로그 회전 및 서식을 처리합니다.
포착되지 않은 예외 및 처리되지 않은 거부를 캡처합니다.

이러한 모듈이 함께 작동하는 방식

도구 호출이 수신되면 MCP 서버는 이를 tools.mjs 의 적절한 핸들러로 라우팅합니다.
도구 핸들러는 매개변수를 검증하고 데이터베이스 쿼리를 구성합니다.
쿼리는 database.mjs 의 함수를 통해 실행되며 pagination.mjs 에서 페이지 매김이 가능합니다.
결과는 포맷되어 클라이언트에게 반환됩니다.
모든 오류는 errors.mjs 를 통해 포착되고 처리됩니다.
모든 작업은 logger.mjs 를 통해 기록됩니다.

이 아키텍처는 다음을 보장합니다.

관심사의 명확한 분리
일관된 오류 처리
종합 로깅
효율적인 데이터베이스 연결 관리
확장 가능한 쿼리 실행

⚙️ 환경 구성 설명

.env 파일은 MS SQL MCP 서버가 데이터베이스에 연결하고 작동하는 방식을 제어합니다. 각 설정에 대한 자세한 설명은 다음과 같습니다.

# Database Connection Settings
DB_USER=your_username           # SQL Server username
DB_PASSWORD=your_password       # SQL Server password
DB_SERVER=your_server_name      # Server hostname or IP address (example: localhost, 10.0.0.1, myserver.database.windows.net)
DB_DATABASE=your_database_name  # Name of the database to connect to

# Server Configuration
PORT=3333                       # Port for the HTTP/SSE server to listen on
TRANSPORT=stdio                 # Connection method: 'stdio' (for Claude Desktop) or 'sse' (for network connections)
SERVER_URL=http://localhost:3333 # Base URL when using SSE transport (must match your PORT setting)

# Advanced Settings
DEBUG=false                     # Set to 'true' for detailed logging (helpful for troubleshooting)
QUERY_RESULTS_PATH=/path/to/query_results  # Directory where query results will be saved as JSON files

연결 유형 설명

stdio 전송

Claude Desktop에 직접 연결할 때 사용하세요
통신은 표준 입출력 스트림을 통해 이루어집니다.
.env 파일에서 TRANSPORT=stdio 설정하세요.
npm start 로 실행

HTTP/SSE 전송

네트워크를 통해 연결할 때 사용(Cursor IDE와 같은 경우)
실시간 통신을 위해 SSE(Server-Sent Events)를 사용합니다.
.env 파일에서 TRANSPORT=sse 설정하세요.
서버 주소와 일치하도록 SERVER_URL 구성하세요.
npm run start:sse 로 실행하세요

SQL Server 연결 예제

로컬 SQL 서버

DB_USER=sa
DB_PASSWORD=YourStrongPassword
DB_SERVER=localhost
DB_DATABASE=AdventureWorks

Azure SQL 데이터베이스

DB_USER=azure_admin@myserver
DB_PASSWORD=YourStrongPassword
DB_SERVER=myserver.database.windows.net
DB_DATABASE=AdventureWorks

쿼리 결과 저장소

쿼리 결과는 QUERY_RESULTS_PATH 에 지정된 디렉터리에 JSON 파일로 저장됩니다. 이렇게 하면 많은 결과 집합이 대화에 과부하를 일으키는 것을 방지할 수 있습니다. 다음 작업을 수행할 수 있습니다.

프로젝트의 기본 query-results 디렉토리를 사용하려면 이 항목을 비워 두십시오.
/Users/username/Documents/query-results 와 같은 사용자 지정 경로를 설정합니다.
도구 응답에서 제공된 UUID를 사용하여 저장된 결과에 액세스합니다.

📝 라이센스

아이에스씨