[ Tech ] 터미널 속의 AI 비서, Claude Code를 위한 MCP 설정 가이드

 

최근 개발자들 사이에서 화제가 되고 있는 Claude Code를 사용해 보셨나요? 터미널 환경에서 코드를 분석하고 수정까지 해주는 놀라운 도구인데요. 하지만 Claude Code의 진정한 강력함은 단순히 코드 편집에 있지 않습니다.

바로 MCP(Model Context Protocol)를 통해 외부 데이터나 도구와 연결될 때 그 진가가 발휘되죠. 오늘은 Claude Code에 MCP 서버를 설정하여, 데이터베이스를 조회하거나 외부 API를 연동하는 등 AI의 작업 범위를 무한히 확장하는 방법을 정리해 보겠습니다.

 

1. MCP란 무엇인가?

---

MCP(Model Context Protocol)는 LLM(대형 언어 모델)이 로컬 데이터 소스나 외부 서비스에 안전하게 접근할 수 있도록 설계된 오픈 표준 프로토콜입니다.

쉽게 말해, Claude에게 "특정 데이터베이스를 읽는 법"이나 "구글 검색을 하는 법" 같은 특수한 기능을 장착해 주는 '확장 팩'이라고 생각하시면 됩니다. Claude Code는 이 MCP를 기본적으로 지원하여, 터미널 환경에서도 풍부한 컨텍스트를 활용할 수 있게 해줍니다.

 

2. 핵심 커맨드로 MCP 서버 관리하기

---

Claude Code에서 MCP 서버를 추가하고 관리하는 방법은 매우 직관적입니다. 기본적인 stdio 방식부터 최신 SSE 방식까지 모두 지원합니다.

 

A. MCP 서버 추가 (stdio)

로컬에 설치된 실행 파일 형태의 MCP 서버를 추가할 때 사용합니다.

# 기본 명령어 형식
claude mcp add <서버이름> <명령어> [인자...]

# 예시: 로컬 서버에 API 키를 포함해 추가하기
claude mcp add my-custom-server -e API_KEY=123 -- /path/to/server arg1

 

B. MCP 서버 추가 (SSE)

URL을 통해 통신하는 SSE(Server-Sent Events) 방식의 서버도 지원합니다.

claude mcp add --transport sse <서버이름> <연결URL>

 

 

C. 서버 목록 확인 및 삭제

현재 연결된 서버 상태를 확인하거나 필요 없는 서버를 제거할 수 있습니다.

claude mcp list             # 등록된 전체 서버 목록 확인
claude mcp get <서버이름>     # 특정 서버의 상세 설정 보기
claude mcp remove <서버이름>  # 서버 연결 해제

 

3. MCP 서버 스코프(Scope)의 이해

---

설정을 어디에 저장하느냐에 따라 팀원과 공유할 수도, 혹은 나만 사용할 수도 있습니다. Claude Code는 세 가지 스코프를 제공합니다.

1. local (기본값): 현재 프로젝트의 로컬 설정에 저장됩니다. 해당 프로젝트를 열 때만 활성화됩니다.
2. project (.mcp.json): 프로젝트 루트 폴더의 .mcp.json 파일에 설정이 저장됩니다. 이 파일을 Git에 포함하면 팀원 모두가 동일한 MCP 도구를 공유할 수 있어 협업에 매우 유리합니다.
3. user: 사용자 글로벌 설정에 저장됩니다. 어떤 프로젝트를 열든 항상 사용할 수 있는 '나만의 도구'가 됩니다.

💡 Pro Tip: 팀 협업 시에는 -s project 플래그를 사용하여 .mcp.json을 생성하고 공통의 DB 스키마 분석 도구 등을 공유해 보세요!

 

4. 실전 활용: Postgres MCP 서버 연결하기

---

가장 유용한 사례 중 하나인 PostgreSQL 데이터베이스 연결입니다. Claude에게 DB 읽기 권한을 주면 스키마를 분석하거나 복잡한 쿼리 결과를 기반으로 코드를 짜달라고 할 수 있습니다.

 

1) 서버 추가

Bash

claude mcp add postgres-server /path/to/postgres-mcp-server --connection-string "postgresql://user:pass@localhost:5432/mydb"

 

2) Claude에게 질문하기

연결이 완료되면 Claude 세션 내에서 다음과 같이 자연어로 물어볼 수 있습니다.

• "우리 users 테이블 스키마 좀 설명해 줘."
• "최근 주문 내역 중에서 결제 실패한 건들만 리스트업 해줘."
• "고객 테이블과 인보이스 테이블의 관계를 알려줘."

 

5. 기존 Claude Desktop 설정 가져오기

---

이미 Claude Desktop 앱에서 MCP 서버를 설정해 두셨나요? 하나씩 다시 입력할 필요가 없습니다.

claude mcp add-from-claude-desktop

이 명령어를 실행하면 데스크탑 앱의 설정을 자동으로 읽어와 선택적으로 가져올 수 있습니다. (macOS 및 WSL 지원)

 

6. 개선 제안: 보안과 성능 최적화

---

Claude Code를 더 안전하고 효율적으로 쓰기 위해 제가 직접 써보며 느낀 개선 팁을 공유합니다.

• 최소 권한 원칙 (Least Privilege): 특히 DB 연결 시에는 반드시 '읽기 전용(Read-only)' 계정을 사용하세요. Claude가 실수로 데이터를 삭제하거나 수정하는 불상사를 방지해야 합니다.
• 환경 변수 활용: API 키나 DB 비밀번호를 직접 커맨드에 노출하기보다 -e KEY=VALUE 플래그를 적극 활용하여 환경 변수로 넘기는 것이 보안상 좋습니다.

타이아웃 설정: 로컬 서버가 응답이 느리다면 MCP_TIMEOUT 환경 변수를 높여서 연결 끊김을 방지하세요.

 

마무리

---

Claude Code와 MCP의 조합은 단순한 '코딩 어시스턴트'를 넘어, '인프라와 데이터를 이해하는 동료 개발자'를 곁에 두는 것과 같습니다.

처음 설정은 조금 번거로울 수 있지만, 한 번 세팅해 두면 프로젝트 분석 속도가 비약적으로 상승하는 것을 체감하실 수 있을 거예요. 오늘 가이드가 여러분의 터미널 환경을 더 스마트하게 만드는 데 도움이 되었길 바랍니다.