Claude Code Hands-on #2 — MCP 서버와 GitHub 통합

이 글은 Anthropic 공식 Course Claude Code in Action 한국어로 번역 & 정리한 글입니다. Hands-on 시리즈 두 번째 편입니다.

MCP 서버란#

Claude Code는 MCP(Model Context Protocol) 서버를 추가해 기본 기능을 확장할 수 있다.

MCP 서버는 원격이나 로컬 머신에서 실행되며, Claude에게 평소에는 없는 새로운 도구와 능력을 부여한다.

가장 많이 쓰이는 MCP 서버 중 하나가 Playwright다. Playwright를 추가하면 Claude가 웹 브라우저를 직접 제어할 수 있게 되어 웹 개발 워크플로우의 가능성이 크게 넓어진다.

Playwright MCP 서버 설치#

Playwright 서버를 Claude Code에 추가하려면 터미널에서 아래 명령어를 실행한다. (Claude Code 안이 아닌 일반 터미널에서 실행해야 한다.)

claude mcp add playwright npx @playwright/mcp@latest

이 명령어는 두 가지를 처리한다.

• MCP 서버 이름을 playwright로 지정
• 로컬 머신에서 서버를 시작하는 명령어를 등록

권한 설정#

MCP 서버 도구를 처음 사용할 때 Claude는 매번 권한을 요청한다. 권한 팝업이 반복되는 게 번거롭다면 설정 파일에서 미리 승인해둘 수 있다.

.claude/settings.local.json 파일을 열고 아래와 같이 allow 배열에 서버를 추가한다.

{
  "permissions": {
    "allow": ["mcp__playwright"],
    "deny": []
  }
}

mcp__playwright에서 언더스코어가 두 개(__)인 것에 주의하자. 이렇게 설정하면 Claude가 매번 권한을 묻지 않고 Playwright 도구를 바로 사용한다.

실전 예시 — 컴포넌트 생성 개선#

Playwright MCP 서버가 실제 워크플로우에서 어떻게 쓰이는지 살펴보자.

수동으로 프롬프트를 테스트하고 조정하는 대신, Claude에게 다음을 시킬 수 있다.

1. 브라우저를 열고 애플리케이션으로 이동
2. 테스트 컴포넌트 생성
3. 시각적 스타일과 코드 품질 분석
4. 분석 결과를 바탕으로 생성 프롬프트 개선
5. 개선된 프롬프트로 새 컴포넌트를 생성해 검증

예를 들어 이렇게 요청할 수 있다.

"Navigate to localhost:3000, generate a basic component, review the styling, and update the generation prompt at @src/lib/prompts/generation.tsx to produce better components going forward."

Claude는 브라우저 도구로 앱과 상호작용하고, 생성된 결과물을 직접 확인한 뒤, 더 나은 디자인을 유도하도록 프롬프트 파일을 수정한다.

핵심 이점은 Claude가 코드만 보는 게 아니라 실제 시각적 결과물을 볼 수 있다는 점이다. 덕분에 스타일 개선에 훨씬 정확한 판단을 내릴 수 있다.

결과 예시#

이 방식을 적용하면 평범한 보라-파랑 그라디언트와 표준 Tailwind 패턴 대신, 훨씬 창의적인 결과를 얻을 수 있다.

• 따뜻한 선셋 그라디언트 (오렌지 → 핑크 → 퍼플)
• 오션뎁스 테마 (틸 → 에메랄드 → 시안)
• 비대칭 레이아웃과 요소 겹치기
• 창의적인 간격과 비관습적인 배치

다른 MCP 서버 탐색#

Playwright는 MCP 서버 생태계의 일부일 뿐이다. 다양한 서버들이 존재한다.

• 데이터베이스 조회 및 수정
• API 테스트와 모니터링
• 파일 시스템 작업
• 클라우드 서비스 연동
• 개발 도구 자동화

자신의 개발 환경에 맞는 MCP 서버를 찾아 추가하면, Claude가 단순한 코드 어시스턴트를 넘어 전체 툴체인과 상호작용하는 개발 파트너로 거듭난다.

GitHub 통합#

Claude Code는 공식 GitHub 통합을 제공한다. Claude가 GitHub Actions 안에서 직접 실행되어 이슈와 PR을 처리한다.

설치#

Claude 안에서 /install-github-app을 실행하면 설치 과정이 안내된다.

• GitHub에 Claude Code 앱 설치
• API 키 추가
• 워크플로우 파일이 담긴 PR 자동 생성

PR을 머지하면 .github/workflows 디렉터리에 두 개의 GitHub Actions가 추가된다.

기본 제공 워크플로우#

Mention Action#

이슈나 PR에서 @claude 를 멘션하면 Claude가 활성화된다.

• 요청을 분석하고 작업 계획 수립
• 전체 코드베이스에 접근해 작업 실행
• 이슈 또는 PR에 직접 결과 응답

Pull Request Action#

PR을 생성하면 Claude가 자동으로:

• 제안된 변경 사항을 리뷰
• 수정의 영향 범위를 분석
• PR에 상세한 리포트를 게시

워크플로우 커스터마이징#

초기 PR을 머지한 후 워크플로우 파일을 프로젝트에 맞게 수정할 수 있다.

프로젝트 셋업 추가#

Claude가 실행되기 전에 환경을 준비하는 단계를 넣을 수 있다.

- name: Project Setup
  run: |
    npm run setup
    npm run dev:daemon

커스텀 지침#

프로젝트 구성에 대한 컨텍스트를 Claude에게 미리 제공한다.

custom_instructions: |
  The project is already set up with all dependencies installed.
  The server is already running at localhost:3000. Logs from it
  are being written to logs.txt. If needed, you can query the
  db with the 'sqlite3' cli. If needed, use the mcp__playwright
  set of tools to launch a browser and interact with the app.

MCP 서버 설정#

GitHub Actions 안에서도 MCP 서버를 활성화할 수 있다.

mcp_config: |
  {
    "mcpServers": {
      "playwright": {
        "command": "npx",
        "args": [
          "@playwright/mcp@latest",
          "--allowed-origins",
          "localhost:3000;cdn.tailwindcss.com;esm.sh"
        ]
      }
    }
  }

도구 권한#

GitHub Actions에서 Claude를 실행할 때는 허용할 도구를 명시적으로 나열해야 한다.

로컬 개발과 달리 권한을 일괄 승인하는 단축키가 없다. MCP 서버의 도구 하나하나를 개별적으로 등록해야 한다.

allowed_tools: "Bash(npm:*),Bash(sqlite3:*),mcp__playwright__browser_snapshot,mcp__playwright__browser_click,..."

운영 팁#

GitHub 통합을 설정할 때 참고할 권장 사항이다.

• 기본 워크플로우로 시작하고 점진적으로 커스터마이징
• 프로젝트별 컨텍스트를 custom_instructions로 제공
• MCP 서버 사용 시 도구 권한을 명확하게 명시
• 복잡한 작업 전에 간단한 태스크로 워크플로우를 먼저 테스트
• 프로젝트 요구사항에 맞는 추가 단계를 구성

정리#