Claude Code Python 개발자 설정 가이드: 가상환경 감지, CLAUDE.md 규칙, MCP 서버 구성
Claude Code Python 개발자 완벽 설정 가이드
Claude Code는 터미널 기반 AI 코딩 에이전트로, Python 개발 환경과 깊이 통합됩니다. 이 가이드에서는 가상환경 자동 감지, 프로젝트 규칙 설정, 데이터베이스·API 연동을 위한 MCP 서버 구성까지 실무 워크플로우를 단계별로 안내합니다.
1단계: Claude Code 설치 및 초기 설정
- Node.js 18+ 설치 확인
node —version
v18.0.0 이상 필요- Claude Code 전역 설치npm install -g @anthropic-ai/claude-code
- 프로젝트 디렉토리에서 실행cd ~/my-python-project
npm install -g @anthropic-ai/claude-codecd ~/my-python-project
claude
최초 실행 시 브라우저에서 Anthropic 계정 인증이 진행됩니다.
2단계: Python 가상환경 자동 감지 설정
Claude Code는 프로젝트 루트의 CLAUDE.md 파일을 통해 가상환경을 인식하고, 올바른 Python 인터프리터를 사용하도록 설정할 수 있습니다.
가상환경 생성 및 활성화
# venv 생성
python -m venv .venv
활성화 (Linux/Mac)
source .venv/bin/activate
활성화 (Windows)
.venv\Scripts\activate
의존성 설치
pip install -r requirements.txt
CLAUDE.md에 가상환경 규칙 등록
프로젝트 루트에 CLAUDE.md 파일을 생성하여 Claude Code가 가상환경을 자동 인식하도록 합니다.
# CLAUDE.md
Python 환경
- 가상환경 경로: .venv/
- Python 버전: 3.11
- 모든 Python 명령은 반드시 .venv/bin/python 또는 .venv/bin/pip 을 사용할 것
- 테스트 실행: .venv/bin/python -m pytest tests/
- 패키지 설치 후 requirements.txt 자동 업데이트: pip freeze > requirements.txt
코드 스타일
- formatter: black (line-length 88)
- linter: ruff
- type checker: mypy —strict
모든 함수에 타입 힌트 필수이 설정으로 Claude Code가
pip install이나python명령 실행 시 항상 가상환경 내 바이너리를 사용합니다.
3단계: CLAUDE.md 프로젝트 규칙 심화 설정
CLAUDE.md는 계층적으로 적용됩니다. 전역, 프로젝트, 하위 디렉토리별 규칙을 설정할 수 있습니다.
계층 구조
| 파일 위치 | 적용 범위 | 용도 |
|---|---|---|
~/.claude/CLAUDE.md | 모든 프로젝트 | 전역 코딩 스타일, 공통 규칙 |
프로젝트루트/CLAUDE.md | 현재 프로젝트 | 프로젝트별 환경, 아키텍처 규칙 |
src/api/CLAUDE.md | 해당 디렉토리 | 모듈별 세부 규칙 |
# CLAUDE.md (프로젝트 루트)
프로젝트 개요
- FastAPI 기반 REST API 서버
- PostgreSQL + SQLAlchemy ORM
- Alembic 마이그레이션 관리
아키텍처 규칙
- app/routers/ 에 엔드포인트 정의
- app/models/ 에 SQLAlchemy 모델
- app/schemas/ 에 Pydantic 스키마
- app/services/ 에 비즈니스 로직 (라우터에 직접 로직 금지)
데이터베이스
- 모델 변경 시 반드시 Alembic 마이그레이션 생성: alembic revision —autogenerate -m “설명”
- 직접 SQL 쿼리 금지, ORM 사용 필수
테스트
- pytest-asyncio 사용
- 테스트 DB는 SQLite in-memory 사용
커버리지 80% 이상 유지: pytest —cov=app tests/
4단계: MCP 서버 구성 — 데이터베이스 및 API 연동
MCP(Model Context Protocol) 서버를 통해 Claude Code가 데이터베이스를 직접 조회하거나 외부 API와 상호작용할 수 있습니다.
MCP 설정 파일 생성
프로젝트 루트에 .mcp.json 파일을 생성합니다.
{
“mcpServers”: {
“postgres”: {
“command”: “npx”,
“args”: [“-y”, “@modelcontextprotocol/server-postgres”],
“env”: {
“DATABASE_URL”: “postgresql://user:password@localhost:5432/mydb”
}
},
“sqlite”: {
“command”: “npx”,
“args”: [“-y”, “@modelcontextprotocol/server-sqlite”, “—db-path”, ”./data/app.db”]
},
“rest-api”: {
“command”: “npx”,
“args”: [“-y”, “@modelcontextprotocol/server-fetch”]
},
“github”: {
“command”: “npx”,
“args”: [“-y”, “@modelcontextprotocol/server-github”],
“env”: {
“GITHUB_TOKEN”: “YOUR_API_KEY”
}
}
}
}
MCP 서버 관리 CLI 명령어
# MCP 서버 추가 (대화형)
claude mcp add postgres npx -y @modelcontextprotocol/server-postgres
# 환경변수와 함께 추가
claude mcp add --env DATABASE_URL=postgresql://user:pass@localhost/db postgres npx -y @modelcontextprotocol/server-postgres
# 등록된 MCP 서버 목록 확인
claude mcp list
# 특정 MCP 서버 제거
claude mcp remove postgres실전 워크플로우: DB 스키마 기반 코드 생성
# Claude Code 실행 후 프롬프트 예시
> PostgreSQL에서 users 테이블 스키마를 조회하고,
해당 스키마에 맞는 SQLAlchemy 모델과 Pydantic 스키마를 생성해줘.
app/models/user.py와 app/schemas/user.py에 작성해줘.MCP 서버가 연결되면 Claude Code가 직접 데이터베이스 스키마를 읽고 정확한 컬럼 타입에 맞는 코드를 생성합니다.
Pro Tips: 파워 유저를 위한 고급 활용
- 슬래시 명령어 활용:
/init으로 CLAUDE.md 자동 생성,/mcp로 MCP 서버 상태 실시간 확인- 비대화형 모드: CI/CD 파이프라인에서claude -p “pytest 실행하고 실패한 테스트 수정해줘” —allowedTools bash,edit활용- 커스텀 슬래시 명령:.claude/commands/디렉토리에 마크다운 파일로 반복 작업 자동화. 예:.claude/commands/migrate.md에 마이그레이션 워크플로우 정의- 멀티 MCP 체이닝: DB 조회 → API 호출 → 코드 생성을 하나의 프롬프트로 처리 가능- Git hooks 연동:claude —allowedTools bash -p “pre-commit 체크 실행”으로 커밋 전 자동 검사
Troubleshooting: 자주 발생하는 오류 해결
| 오류 | 원인 | 해결 방법 |
|---|---|---|
CLAUDE.md not found | 프로젝트 루트 외부에서 실행 | cd로 프로젝트 루트 이동 후 claude 재실행 |
MCP server failed to start | Node.js 미설치 또는 패키지 없음 | node --version 확인 후 npx 캐시 초기화: npx clear-npx-cache |
Permission denied: .venv/bin/python | 가상환경 비활성 상태 | source .venv/bin/activate 실행 또는 CLAUDE.md에 절대 경로 지정 |
DATABASE_URL connection refused | DB 서버 미실행 또는 포트 불일치 | DB 서비스 상태 확인: pg_isready -h localhost -p 5432 |
| MCP 서버 인증 오류 | API 키 만료 또는 누락 | .mcp.json의 env 값 확인, 토큰 재발급 |
Q1: CLAUDE.md와 .mcp.json 파일은 Git에 커밋해야 하나요?
CLAUDE.md는 팀 공통 규칙이므로 Git에 커밋하는 것을 권장합니다. 반면 .mcp.json에 데이터베이스 비밀번호나 API 키가 포함된 경우 .gitignore에 추가하고, 환경변수로 대체하세요. 팀원 공유가 필요하면 .mcp.json.example을 템플릿으로 커밋하는 방법을 추천합니다.
Q2: 가상환경이 여러 개인 경우(예: poetry, conda) Claude Code가 올바른 환경을 인식하나요?
CLAUDE.md에 사용할 패키지 매니저와 환경 활성화 명령을 명시하면 됩니다. 예를 들어 Poetry의 경우 poetry run python, Conda의 경우 conda run -n myenv python을 기본 Python 실행 명령으로 지정하세요. Claude Code는 CLAUDE.md에 작성된 규칙을 최우선으로 따릅니다.
Q3: MCP 서버를 통해 프로덕션 데이터베이스에 연결해도 안전한가요?
개발·스테이징 환경에서만 사용하는 것을 강력히 권장합니다. 프로덕션 DB 연결이 필요하다면 읽기 전용 복제본(read replica)에 연결하고, 데이터베이스 사용자 권한을 SELECT만 허용하도록 제한하세요. Claude Code의 권한 모드에서 도구 실행 전 사용자 확인을 활성화하면 추가적인 안전 장치가 됩니다.