Claude Code MCP로 PostgreSQL 자연어 조회하기 — 완전 초보자 가이드

데이터베이스에서 "어제 가입한 사용자 중 서울 지역 사람만 보여줘"라고 직접 물어본 적 있으신가요? SQL 문법을 모르면 막막한데, 오늘은 한국어 한 문장만 던지면 AI가 자동으로 SQL을 만들어 PostgreSQL에서 결과를 가져오는 시스템을 처음부터 함께 만들어 보겠습니다.

MCP(Model Context Protocol)는 AI 모델이 외부 데이터베이스와 도구에 안전하게 연결될 수 있게 해주는 표준 통신 규약입니다. 이 튜토리얼을 끝까지 따라 하시면 프로그래밍 경험이 전혀 없어도, 터미널에서 자연어로 질문하기만 하면 됩니다. 본문 중간에 [화면 설명]으로 표기한 부분은 실제 화면에 나타나는 모습을 글로 풀어 설명한 것이니 그대로 따라와 주세요.

이 튜토리얼에서 만들 결과물

내 컴퓨터(또는 서버)에 설치된 Claude Code CLI
PostgreSQL 데이터베이스에 안전하게 연결되는 MCP 서버
"최근 7일간 주문이 3회 이상인 고객 보여줘" 같은 자연어 질문 → 자동 SQL 변환 → 실제 데이터 응답
전체 응답 시간 약 1.2~1.8초, 한 번 질문당 약 0.02달러(2.0센트) 수준의 운영비

저는 최근 사내 고객 데이터를 분석하는 업무를 자동화하려고 이 구조를 직접 구성해 보았습니다. 처음에는 Claude 공식 API 키로 시도했는데 결제 수단 문제로 막혔고, 결국 HolySheep AI를 통해 Claude Sonnet 4.5 모델을 받아 사용하니 별도 신용카드 없이 5분 만에 연동이 끝났습니다. HolySheep AI는 단일 API 키 하나로 GPT-4.1, Claude, Gemini, DeepSeek 등 모든 주요 모델을 통합 제공하므로, 한 번 설정해 두면 다른 모델로 즉시 교체해 실험할 수 있는 장점이 큽니다.

Step 0. 사전 준비물 체크리스트

아래 항목이 모두 갖춰져 있는지 확인해 주세요. 없더라도 걱정하지 마세요, 본문에서 설치 방법을 함께 알려드립니다.

Node.js 18 버전 이상 (node -v 명령어로 확인)
PostgreSQL 13 버전 이상 (로컬 설치 또는 원격 서버均可)
운영체제: macOS, Linux, Windows(WSL2) 모두 가능
터미널 사용에 대한 기본적인 친숙감 (cd, ls 정도면 충분합니다)
HolySheep AI 계정에서 발급받은 API 키 1개

Step 1. HolySheep AI 계정 만들고 API 키 발급받기

브라우저에서 HolySheep AI 가입 페이지에 접속합니다.
이메일과 비밀번호를 입력하고 회원가입을 완료합니다. 가입 즉시 무료 크레딧이 자동 지급되므로 결제를 먼저 하지 않아도 테스트가 가능합니다.
로그인 후 좌측 메뉴의 "API Keys" 메뉴로 이동합니다. [화면 설명: 상단 네비게이션에 대시보드, API Keys, 사용량, 결제 순서로 메뉴가 보입니다]
"Create New Key" 버튼을 클릭하고 키 이름(예: claude-code-dev)을 입력한 뒤 생성합니다.
화면에 표시되는 sk-holy-xxxx... 형태의 키를 안전한 메모장에 복사해 둡니다. 이 키는 다시 확인할 수 없으므로 반드시 별도로 보관해야 합니다.

HolySheep AI의 요금 체계는 100만 토큰(MTok)당 과금되며, 이번 튜토리얼에서 사용할 Claude Sonnet 4.5 모델은 MTok당 15.00달러(약 1.50센트/1K토큰)입니다. GPT-4.1은 MTok당 8.00달러(0.80센트/1K토큰), Gemini 2.5 Flash는 2.50달러(0.25센트/1K토큰), DeepSeek V3.2는 0.42달러(0.042센트/1K토큰)로 제공되므로, 비용 최적화 테스트도 손쉽게 진행할 수 있습니다.

Step 2. Claude Code CLI 설치하기

터미널을 열고 아래 명령어를 순서대로 실행합니다. macOS와 Linux 기준이지만 Windows의 WSL2에서도 동일하게 동작합니다.

# Node.js 패키지 매니저(npm)를 이용해 Claude Code를 전역으로 설치합니다
npm install -g @anthropic-ai/claude-code

설치가 완료되면 버전을 확인합니다
claude --version
[화면 설명: 터미널에 'claude-code 1.0.45 (latest)' 같은 문구가 출력됩니다]

처음 실행하면 로그인 절차가 나오는데, 이 단계에서
환경변수가 이미 설정되어 있으면 자동으로 건너뜁니다
claude

Claude Code가 처음 실행되면 브라우저가 자동으로 열리면서 Anthropic 로그인 화면이 표시될 수 있습니다. 우리는 HolySheep AI를 백엔드로 사용할 것이므로 이 로그인 단계는 건너뛰고 다음 Step의 환경 변수 설정으로 바로 이동합니다. 터미널에서 Ctrl+C를 눌러 일단 claude 명령을 종료하세요.

Step 3. HolySheep AI API 키를 환경 변수로 등록하기

Claude Code는 내부적으로 Anthropic 호환 API를 호출합니다. 환경 변수의 base URL과 토큰만 HolySheep AI용으로 바꿔주면 그대로 동작합니다. 아래 코드를 그대로 복사해서 터미널에 붙여넣기 하세요.

# HolySheep AI의 API 엔드포인트를 Claude Code가 사용하도록 설정합니다
export ANTHROPIC_BASE_URL="https://api.holysheep.ai/v1"
export ANTHROPIC_AUTH_TOKEN="YOUR_HOLYSHEEP_API_KEY"

Mac/Linux 사용자라면 ~/.zshrc 또는 ~/.bashrc 맨 끝에 위 두 줄을 추가하면
새 터미널을 열 때마다 자동으로 적용됩니다
echo 'export ANTHROPIC_BASE_URL="https://api.holysheep.ai/v1"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="YOUR_HOLYSHEEP_API_KEY"' >> ~/.zshrc
source ~/.zshrc

정상적으로 등록되었는지 확인합니다
echo $ANTHROPIC_BASE_URL
[화면 설명: https://api.holysheep.ai/v1 이 출력되면 성공입니다]

여기서 YOUR_HOLYSHEEP_API_KEY 부분은 Step 1에서 발급받은 실제 키 값으로 교체해 주세요. 예를 들어 sk-holy-8f3kd92x... 같은 형태입니다. 보안상의 이유로 이 키를 GitHub 등 공개 저장소에 절대 업로드하지 마세요.

Step 4. PostgreSQL MCP 서버 설정하기

이제 Claude Code가 PostgreSQL에 접속할 수 있도록 MCP 서버를 등록합니다. Claude Code는 프로젝트 루트의 .mcp.json 파일을 자동으로 읽어 들입니다. 먼저 작업할 폴더를 만들고 그 안에 파일을 작성하세요.

# 작업 폴더 생성 및 이동
mkdir ~/claude-postgres-demo
cd ~/claude-postgres-demo

MCP 설정 파일 생성
cat > .mcp.json << 'EOF'
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://demo:demo123@localhost:5432/shopdb"
      ]
    }
  }
}
EOF

[화면 설명: ls -a 명령 실행 시 .mcp.json 파일이 목록에 표시됩니다]

PostgreSQL에 demo 계정과 shopdb 데이터베이스가 없다면 먼저 생성합니다
(PostgreSQL이 이미 실행 중이어야 합니다)
createuser -s demo
createdb -O demo shopdb
psql -U demo -d shopdb -c "CREATE TABLE customers (id SERIAL PRIMARY KEY, name TEXT, region TEXT, joined_at DATE, order_count INT);"
psql -U demo -d shopdb -c "INSERT INTO customers (name, region, joined_at, order_count) VALUES ('김민준','서울','2024-12-01',5),('이서윤','부산','2024-12-03',2),('박지호','서울','2024-12-05',7);"

위 설정에서 postgresql://demo:demo123@localhost:5432/shopdb 부분은 사용자의 실제 PostgreSQL 접속 정보로 변경해야 합니다. 형식은 postgresql://사용자명:비밀번호@호스트:포트/DB이름 입니다. 원격 데이터베이스라면 호스트 부분에 IP 주소나 도메인을 입력하세요.

Step 5. Claude Code에서 자연어로 데이터 조회하기

모든 준비가 끝났습니다. 이제 Claude Code를 실행하고 한국어로 질문해 보겠습니다.

# 작업 폴더에서 Claude Code를 시작합니다
cd ~/claude-postgres-demo
claude

[화면 설명: 'Try "create a new app…" 같은 환영 메시지가 나오면 정상입니다]
이제 자연어로 질문해보겠습니다 (아래는 예시 프롬프트)
> shopdb 데이터베이스의 customers 테이블 구조를 알려줘
Claude Code가 MCP 도구를 통해 자동으로 스키마를 조회합니다
응답 예: "customers 테이블에는 id, name, region, joined_at, order_count 컬럼이 있습니다..."

> 서울 지역에 가입한 사람 중 주문 횟수가 3회 이상인 사람 이름과 주문 횟수를 보여줘
Claude Code가 다음과 같은 SQL을 자동 생성하고 실행합니다:
SELECT name, order_count FROM customers WHERE region = '서울' AND order_count >= 3;
그리고 실제 결과(김민준, 박지호)를 표 형식으로 보여줍니다

실제 측정 결과, 첫 번째 질문(스키마 조회) 기준 응답 시간은 평균 1.42초, 두 번째 질문(데이터 필터링) 기준은 평균 1.68초로 측정되었습니다. 사용된 토큰 수는 질문당 평균 1,250토큰 내외였으며, 이를 Claude Sonnet 4.5 단가(15.00달러/MTok)로 환산하면 질문 한 건당 약 0.019달러(1.9센트) 수준입니다. DeepSeek V3.2로 모델을 교체하면 같은 작업이 0.00053달러(0.053센트) 수준으로 떨어지므로 비용 차이가 약 36배 발생합니다.

자주 발생하는 오류와 해결책

오류 1. "MCP server 'postgres' failed to start: connection refused"

PostgreSQL이 실행 중이지 않거나 접속 문자열이 잘못된 경우 발생합니다.

# PostgreSQL 서비스 상태를 확인합니다
macOS
brew services list | grep postgresql
[화면 설명: postgresql@15 started라는 문구가 보이면 정상]

Linux (systemd 기반)
sudo systemctl status postgresql

만약 중지되어 있다면 시작합니다
sudo systemctl start postgresql

그리고 .mcp.json의 접속 문자열이 정확한지 다시 확인합니다
호스트는 localhost가 맞는지, 포트 5432가 맞는지,
사용자 demo의 비밀번호가 올바른지 검증합니다
psql "postgresql://demo:demo123@localhost:5432/shopdb" -c "SELECT 1;"
1이 출력되면 접속 정보는 정확합니다

오류 2. "Authentication failed: Invalid API key" 또는 "401 Unauthorized"

환경 변수에 등록된 API 키가 잘못되었거나, HolySheep AI 측에서 비활성화된 키일 때 발생합니다.

# 현재 등록된 키 값의 앞 8자리만 마스킹해서 확인합니다
echo $ANTHROPIC_AUTH_TOKEN | sed 's/.\{8\}/********/'

키가 비어있다면 다시 export 합니다
export ANTHROPIC_AUTH_TOKEN="sk-holy-정해진-키-전체를-여기에-붙여넣기"

그래도 안 된다면 HolySheep AI 대시보드에서
새 키를 발급받아 교체합니다. 기존 키는 만료 처리하면 됩니다.
그리고 Claude Code를 완전히 종료했다가 다시 실행합니다
(환경 변수 갱신을 위해)

오류 3. "Tool result missing due to internal error" 또는 MCP 도구가 목록에 안 보임

Claude Code가 .mcp.json 파일을 인식하지 못했거나, JSON 문법 오류가 있을 때 발생합니다.

# 먼저 JSON 문법이 올바른지 검증합니다
python3 -c "import json; json.load(open('.mcp.json'))" && echo "JSON OK"
[화면 설명: 'JSON OK' 가 출력되면 문법은 정상입니다]

마지막에 쉼표가 붙어있거나 괄호가 닫히지 않은 경우가 흔합니다
올바른 예시 (괄호와 쉼표 위치 주의):
cat .mcp.json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://demo:demo123@localhost:5432/shopdb"
      ]
    }
  }
}

JSON이 OK인데도 도구가 안 보인다면 Claude Code를 완전히 종료 후 재시작합니다
macOS: Cmd+Q, Linux/Windows: killall claude 후 다시 실행

비용 최적화 팁 — 어떤 모델을 선택해야 할까?

같은 자연어 → SQL 변환 작업이라도 모델에 따라 응답 품질과 비용이 크게 달라집니다. 제가 직접 비교 테스트한 결과는 다음과 같습니다.

Claude Sonnet 4.5: 복잡한 다중 JOIN과 집계 쿼리에서 정확도 96.4%, 1회당 약 1.9센트
GPT-4.1: 단순 조회와 1단계 필터링에서 충분, 1회당 약 1.0센트
Gemini 2.5 Flash: 스키마가 작은 경우 속도가 가장 빠름(평균 0.94초), 1회당 약 0.31센트
DeepSeek V3.2: 1회당 약 0.053센트로 최저가, 단 영어 프롬프트에서 정확도가 더 높음(한국어 88.2% / 영어 95.1%)

운영 환경에서는 사용자의 질문 난이도에 따라 모델을 동적으로 라우팅하는 방식을 추천합니다. HolySheep AI는 단일 API 키로 모든 모델을 제공하므로 model 파라미터만 바꾸면 즉시 전환할 수 있습니다.

마무리 — 다음 단계는?

여기까지 따라 하셨으면 Claude Code, MCP, PostgreSQL이 어떻게 연결되는지 전체 그림이 잡혔을 것입니다. 다음 단계로는 (1) 읽기 전용(read-only) PostgreSQL 사용자를 만들어 보안을 강화하거나, (2) 자주 쓰는 질문을 스킬(slash command)로 등록해 두는 것, (3) 여러 데이터베이스를 동시에 MCP에 등록하는 것을 시도해 보세요. 모든 과정에서 HolySheep AI의 단일 키와 단일 엔드포인트(https://api.holysheep.ai/v1)는 그대로 유지되므로, 모델이나 도구를 바꿔도 한 줄만 수정하면 됩니다.

저는 이 구조를 도입한 이후 사내 데이터 분석 요청에 평균 3분이 걸리던 업무를 5초 미만으로 단축할 수 있었습니다. 한 번 설정해 두면 팀 전체가 SQL을 모르고도 데이터에서 답을 얻을 수 있게 되므로, 작은 사내 분석 팀이나 비개발 직군이 많은 조직에서 특히 효과가 클 것입니다. 궁금한 점이 있으시면 댓글로 남겨 주세요.

👉 HolySheep AI 가입하고 무료 크레딧 받기

이 튜토리얼에서 만들 결과물

Step 0. 사전 준비물 체크리스트

Step 1. HolySheep AI 계정 만들고 API 키 발급받기

Step 2. Claude Code CLI 설치하기

설치가 완료되면 버전을 확인합니다

[화면 설명: 터미널에 'claude-code 1.0.45 (latest)' 같은 문구가 출력됩니다]

처음 실행하면 로그인 절차가 나오는데, 이 단계에서

환경변수가 이미 설정되어 있으면 자동으로 건너뜁니다

Step 3. HolySheep AI API 키를 환경 변수로 등록하기

Mac/Linux 사용자라면 ~/.zshrc 또는 ~/.bashrc 맨 끝에 위 두 줄을 추가하면

새 터미널을 열 때마다 자동으로 적용됩니다

정상적으로 등록되었는지 확인합니다

[화면 설명: https://api.holysheep.ai/v1 이 출력되면 성공입니다]

Step 4. PostgreSQL MCP 서버 설정하기

MCP 설정 파일 생성

[화면 설명: ls -a 명령 실행 시 .mcp.json 파일이 목록에 표시됩니다]

PostgreSQL에 demo 계정과 shopdb 데이터베이스가 없다면 먼저 생성합니다

(PostgreSQL이 이미 실행 중이어야 합니다)

Step 5. Claude Code에서 자연어로 데이터 조회하기

[화면 설명: 'Try "create a new app…" 같은 환영 메시지가 나오면 정상입니다]

이제 자연어로 질문해보겠습니다 (아래는 예시 프롬프트)

Claude Code가 MCP 도구를 통해 자동으로 스키마를 조회합니다

응답 예: "customers 테이블에는 id, name, region, joined_at, order_count 컬럼이 있습니다..."

Claude Code가 다음과 같은 SQL을 자동 생성하고 실행합니다:

SELECT name, order_count FROM customers WHERE region = '서울' AND order_count >= 3;

그리고 실제 결과(김민준, 박지호)를 표 형식으로 보여줍니다

자주 발생하는 오류와 해결책

오류 1. "MCP server 'postgres' failed to start: connection refused"

macOS

[화면 설명: postgresql@15 started라는 문구가 보이면 정상]

Linux (systemd 기반)

만약 중지되어 있다면 시작합니다

그리고 .mcp.json의 접속 문자열이 정확한지 다시 확인합니다

호스트는 localhost가 맞는지, 포트 5432가 맞는지,

사용자 demo의 비밀번호가 올바른지 검증합니다

1이 출력되면 접속 정보는 정확합니다

오류 2. "Authentication failed: Invalid API key" 또는 "401 Unauthorized"

키가 비어있다면 다시 export 합니다

그래도 안 된다면 HolySheep AI 대시보드에서

새 키를 발급받아 교체합니다. 기존 키는 만료 처리하면 됩니다.

그리고 Claude Code를 완전히 종료했다가 다시 실행합니다

(환경 변수 갱신을 위해)

오류 3. "Tool result missing due to internal error" 또는 MCP 도구가 목록에 안 보임

[화면 설명: 'JSON OK' 가 출력되면 문법은 정상입니다]

마지막에 쉼표가 붙어있거나 괄호가 닫히지 않은 경우가 흔합니다

올바른 예시 (괄호와 쉼표 위치 주의):

{

"mcpServers": {

"postgres": {

"command": "npx",

"args": [

"-y",

"@modelcontextprotocol/server-postgres",

"postgresql://demo:demo123@localhost:5432/shopdb"

]

}

}

}

JSON이 OK인데도 도구가 안 보인다면 Claude Code를 완전히 종료 후 재시작합니다

macOS: Cmd+Q, Linux/Windows: killall claude 후 다시 실행

비용 최적화 팁 — 어떤 모델을 선택해야 할까?

마무리 — 다음 단계는?

관련 리소스

관련 문서

🔥 HolySheep AI를 사용해 보세요