Claude MCP 서버로 PostgreSQL 연동

Claude에서 MCP 서버를 구축하고 PostgreSQL 데이터베이스를 연동하는 실전 가이드

---

MCP란 무엇인가

MCP(Model Context Protocol) 는 Anthropic에서 개발한 표준 프로토콜로, Claude와 외부 데이터 소스를 연결하는 인터페이스임.

핵심 개념

MCP는 Claude가 외부 시스템과 통신할 수 있도록 하는 브릿지 역할을 함. 데이터베이스, API, 파일 시스템 등 다양한 데이터 소스에 접근 가능함.

┌─────────────┐         ┌─────────────┐         ┌──────────────┐
│             │         │             │         │              │
│   Claude    │ ◄─────► │ MCP Server  │ ◄─────► │  PostgreSQL  │
│             │         │             │         │              │
└─────────────┘         └─────────────┘         └──────────────┘
    자연어 질의          프로토콜 변환            SQL 실행

MCP의 장점

특징	설명
표준화	통일된 인터페이스로 다양한 데이터 소스 연결
안전성	읽기 전용 접근으로 데이터 무결성 보장
확장성	플러그인 방식으로 쉽게 확장 가능
편의성	자연어로 데이터 조회 및 분석 가능

---

환경 구축하기

필수 요구사항

MCP 서버 구축을 위해 다음 도구가 필요함:

• Node.js: MCP 서버 실행 환경
• Claude Code CLI: Claude 명령줄 도구
• PostgreSQL: 연동할 데이터베이스 인스턴스

Node.js 설치 확인

node --version
npm --version

PostgreSQL 설치 확인

psql --version

---

MCP 서버 설정

1. 설정 파일 위치

Claude의 MCP 설정 파일은 다음 위치에 있음:

~/.claude/config.json

2. PostgreSQL MCP 서버 추가

설정 파일을 열고 다음 내용을 추가함:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/mydb"
      ]
    }
  }
}

설정 항목 설명:

• "postgres": MCP 서버의 이름 (임의로 지정 가능)
• "command": 실행할 명령어 (npx는 npm 패키지를 즉시 실행)
• "args": 명령어 인자
  • -y: 자동으로 yes 응답
  • @modelcontextprotocol/server-postgres: PostgreSQL MCP 서버 패키지
  • postgresql://localhost/mydb: PostgreSQL 연결 URL

3. 연결 문자열 설정

PostgreSQL 연결 문자열 형식:

postgresql://[username[:password]@][host][:port][/database]

로컬 개발 환경:

"args": [
  "-y",
  "@modelcontextprotocol/server-postgres",
  "postgresql://localhost/mydb"
]

사용자 인증:

"args": [
  "-y",
  "@modelcontextprotocol/server-postgres",
  "postgresql://user:password@localhost/mydb"
]

원격 서버:

"args": [
  "-y",
  "@modelcontextprotocol/server-postgres",
  "postgresql://user:password@remote-host:5432/mydb"
]

SSL 연결:

"args": [
  "-y",
  "@modelcontextprotocol/server-postgres",
  "postgresql://user:password@remote-host:5432/mydb?sslmode=require"
]

4. 여러 MCP 서버 설정

여러 데이터베이스를 동시에 연결할 수 있음:

{
  "mcpServers": {
    "postgres-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://user:pass@prod-server:5432/production"
      ]
    },
    "postgres-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/development"
      ]
    },
    "postgres-test": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/test"
      ]
    }
  }
}

---

MCP 서버 시작 및 확인

1. Claude 재시작

설정 파일을 수정한 후 Claude를 재시작해야 함:

# Claude 프로세스 종료 후 다시 시작
claude

2. MCP 서버 연결 확인

Claude를 시작하면 MCP 서버가 자동으로 실행됨. 연결 상태 확인:

사용 가능한 도구 확인:

Available MCP Tools:
- mcp__postgres__query: Execute read-only SQL queries

3. 연결 테스트

간단한 쿼리로 연결을 테스트함:

자연어로 질의:

"테이블 목록 보여줘"

또는 직접 SQL 요청:

"SELECT * FROM pg_tables WHERE schemaname = 'public' 실행해줘"

정상적으로 테이블 목록이 출력되면 연결 성공임.

---

실전 사용 예제

기본 데이터베이스 조회

MCP 서버가 연결되면 자연어로 데이터베이스 조회 가능:

예제 1: 테이블 목록

사용자: "데이터베이스에 어떤 테이블이 있어?"
Claude: [자동으로 적절한 쿼리 실행 후 결과 제공]

예제 2: 테이블 구조 확인

사용자: "users 테이블 구조 알려줘"
Claude: [테이블 스키마 정보 제공]

예제 3: 데이터 조회

사용자: "users 테이블에서 최근 가입한 사용자 10명 보여줘"
Claude: [데이터 조회 및 분석 결과 제공]

자동 쿼리 생성

Claude가 자연어를 SQL로 자동 변환:

사용자: "이번 달 주문 건수가 몇 개야?"
Claude: → SELECT COUNT(*) FROM orders
          WHERE created_at >= DATE_TRUNC('month', CURRENT_DATE)

사용자: "가장 많이 팔린 상품 5개 알려줘"
Claude: → SELECT product_name, COUNT(*) as sales
          FROM orders
          GROUP BY product_name
          ORDER BY sales DESC
          LIMIT 5

---

고급 설정

환경 변수 활용

민감한 정보는 환경 변수로 관리하는 것이 좋음:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${DATABASE_URL}"
      ],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost/mydb"
      }
    }
  }
}

또는 시스템 환경 변수 사용:

# .bashrc 또는 .zshrc
export DATABASE_URL="postgresql://user:password@localhost/mydb"

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${DATABASE_URL}"
      ]
    }
  }
}

타임아웃 설정

장시간 실행되는 쿼리를 위해 타임아웃을 설정할 수 있음:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/mydb"
      ],
      "timeout": 30000
    }
  }
}

연결 풀 설정

PostgreSQL 연결 풀링 옵션:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/mydb?max_pool_size=10&min_pool_size=2"
      ]
    }
  }
}

---

트러블슈팅

MCP 서버가 시작되지 않는 경우

증상: Claude 시작 시 MCP 서버 연결 실패

해결 방법:

1. Node.js 설치 확인

node --version
npm --version

2. 설정 파일 확인

cat ~/.claude/config.json

3. JSON 문법 오류 확인

• 콤마 누락 확인
• 괄호 짝 맞는지 확인
• 따옴표 올바른지 확인

4. PostgreSQL 연결 확인

psql -h localhost -U user -d mydb

인증 오류

증상: password authentication failed 에러

해결 방법:

1. 사용자 계정 확인

SELECT usename FROM pg_user;

2. 비밀번호 확인

psql -h localhost -U user -d mydb

3. pg_hba.conf 설정 확인

# PostgreSQL 설정 파일 위치 확인
psql -c "SHOW hba_file"

연결 거부 오류

증상: Connection refused 에러

해결 방법:

1. PostgreSQL 실행 확인

pg_isready
# 또는
sudo systemctl status postgresql

2. 포트 확인

netstat -an | grep 5432

3. 방화벽 설정 확인

sudo ufw status

쿼리 권한 오류

증상: permission denied 에러

해결 방법:

MCP 서버는 읽기 전용이므로 SELECT 권한만 필요:

GRANT SELECT ON ALL TABLES IN SCHEMA public TO user;

---

보안 고려사항

읽기 전용 접근

MCP 서버는 기본적으로 읽기 전용 쿼리만 지원:

허용	차단
SELECT	INSERT
SHOW	UPDATE
DESCRIBE	DELETE
EXPLAIN	DROP

전용 사용자 생성

MCP 전용 읽기 전용 사용자 생성 권장:

-- 읽기 전용 사용자 생성
CREATE USER mcp_readonly WITH PASSWORD 'secure_password';

-- SELECT 권한 부여
GRANT CONNECT ON DATABASE mydb TO mcp_readonly;
GRANT USAGE ON SCHEMA public TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;

-- 향후 생성될 테이블에도 자동 권한 부여
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT ON TABLES TO mcp_readonly;

연결 정보 보호

민감한 연결 정보는 환경 변수나 별도 파일로 관리:

# .env 파일 생성
DATABASE_URL=postgresql://mcp_readonly:password@localhost/mydb

# 권한 설정
chmod 600 .env

SSL/TLS 암호화

프로덕션 환경에서는 SSL 연결 필수:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://user:pass@host:5432/db?sslmode=require"
      ]
    }
  }
}

SSL 모드 옵션:

• disable: SSL 사용 안 함
• require: SSL 필수
• verify-ca: CA 인증서 검증
• verify-full: 호스트명까지 검증

---

실전 활용 사례

1. 데이터 탐색

자연어로 데이터베이스 구조와 내용 탐색:

"어떤 테이블이 있어?"
"users 테이블 구조 알려줘"
"users 테이블 레코드 몇 개야?"
"최근 생성된 데이터 10개 보여줘"

2. 비즈니스 분석

비즈니스 질문을 바로 데이터로 확인:

"이번 달 신규 가입자 수는?"
"어제 매출은 얼마야?"
"가장 인기 있는 카테고리는?"
"지역별 주문 분포 보여줘"

3. 데이터 검증

데이터 품질 확인:

"NULL 값이 있는 레코드 있어?"
"중복된 이메일 있어?"
"유효하지 않은 날짜 데이터 있어?"

4. 트러블슈팅

문제 발생 시 빠른 확인:

"최근 1시간 에러 로그 보여줘"
"실패한 트랜잭션 조회해줘"
"응답 시간이 긴 API 요청 찾아줘"

---

MCP vs 기존 방식 비교

기존 방식

# 터미널에서 psql 접속
psql -h localhost -U user -d mydb

# SQL 작성
mydb=# SELECT COUNT(*) FROM users WHERE created_at > NOW() - INTERVAL '7 days';

# 결과 확인
 count
-------
   143

MCP 방식

사용자: "지난 7일간 가입한 사용자 수 알려줘"
Claude: 지난 7일간 143명의 사용자가 가입했습니다.

장점:

• SQL 문법 몰라도 됨
• 자연어로 질의
• 결과 자동 해석
• 연속 질문 가능

---

마치며

MCP를 활용하면 Claude가 PostgreSQL 데이터베이스에 직접 접근하여 자연어로 데이터를 조회할 수 있음.

구축 요약:

1. ~/.claude/config.json 파일 생성
2. PostgreSQL MCP 서버 설정 추가
3. 연결 문자열 입력
4. Claude 재시작
5. 자연어로 데이터 조회

핵심 장점:

• 쉬운 설정: 설정 파일 하나로 연동 완료
• 자연어 지원: SQL 없이 데이터 조회
• 안전한 접근: 읽기 전용으로 데이터 보호
• 빠른 분석: 대화형으로 즉시 데이터 확인

MCP 서버 구축은 간단하지만, 데이터 분석 워크플로우를 혁신적으로 개선할 수 있음.

---

참고 자료

공식 문서:

• MCP 공식 문서
• Claude Code CLI
• PostgreSQL 문서

MCP 서버:

• MCP Server 저장소
• PostgreSQL MCP Server

---