🔌 Claude Code 입문
MCP 서버 연결로 Claude Code에 깃허브·DB·브라우저 붙이는 법
코드는 잘 짜는데 정작 내 저장소나 데이터베이스는 못 건드리는 Claude Code, 답답하셨죠? 그 손발을 달아주는 열쇠가 바로 MCP입니다. 오늘은 깃허브·데이터베이스·브라우저를 순서대로 붙이고 확인하는 방법을 비개발자 눈높이에서 정리해봤습니다.
📌 3줄 요약
- MCP는 Claude Code와 외부 도구를 잇는 '표준 콘센트' — 한 번 익히면 도구 이름만 바꿔 끼우면 됩니다.
- 깃허브·데이터베이스·브라우저 모두
claude mcp add한 줄로 붙이고, 자연어로 시킬 수 있습니다. - 붙인 뒤엔
claude mcp list로 확인하고, 안 되면 지웠다 다시 붙이며 두세 개만 남기세요.
MCP 서버가 대체 무엇이고 왜 붙이나요
Claude Code를 쓰다 보면 답답한 순간이 있습니다. 코드는 잘 짜는데, 정작 제 깃허브 저장소나 데이터베이스는 직접 못 건드리는 상황이죠. 분명 옆에 똑똑한 조수가 앉아 있는데, 그 조수의 손이 책상 밖으로는 못 나가는 느낌이랄까요.
아이디어는 다 알려주는데 실행은 결국 제 몫으로 남으니 아쉬웠습니다. 이 답답함을 한 번에 풀어주는 열쇠가 바로 MCP입니다.
🔍 MCP가 뭐예요?
MCP는 Model Context Protocol(모델 컨텍스트 프로토콜)의 약자입니다. 쉽게 말하면 Claude Code와 외부 도구를 이어주는 표준 규격입니다.
여기서 '표준'이라는 단어가 핵심인데요, 서로 다른 도구들을 하나의 약속된 방식으로 연결한다는 뜻이거든요. 이 약속 덕분에 새로운 도구가 나와도 같은 요령으로 붙일 수 있습니다.
콘센트를 떠올리면 이해가 빠릅니다. 나라마다 플러그 모양이 다르면 불편하듯, 도구마다 연결 방식이 다르면 골치 아프겠죠. 여행 갈 때마다 나라별 어댑터를 챙겨야 한다고 생각하면 벌써 피곤해집니다.
개발 도구의 세계도 예전엔 딱 그런 상황이었습니다.
MCP는 그 플러그 모양을 하나로 통일한 겁니다. 덕분에 깃허브든 데이터베이스든 같은 방식으로 꽂아 쓸 수 있습니다.
한 번 연결 요령을 익혀두면 그다음부터는 도구 이름만 바꿔 끼우면 되구요. 처음 배우는 부담은 딱 한 번뿐이라는 뜻입니다.
이게 비개발자에게는 특히 반가운 지점이라고 생각합니다.
이걸 붙이면 Claude Code가 할 수 있는 일이 확 늘어납니다. 저장소 이슈를 읽어오고, DB에서 데이터를 조회하고, 브라우저로 웹페이지를 열어보는 일까지 가능해집니다.
단순히 코드를 보여주는 수준을 넘어, 실제 작업을 대신 처리해주는 단계로 올라서는 셈이죠. 말로만 시켜도 실제 결과물이 눈앞에 나오는 경험은 생각보다 강렬합니다.
💬 직접 써본 소감
제가 직접 써보니, MCP를 붙이기 전과 후는 완전히 다른 도구였습니다. 붙이기 전엔 코드만 짜주는 조수였다면, 붙인 뒤엔 실제로 손발이 되어 움직이는 느낌이더군요.
처음엔 "이게 되나?" 싶었는데, 저장소 이슈를 술술 읽어오는 걸 보고 생각이 바뀌었습니다. 한 번 이 편리함을 맛보면 예전 방식으로는 돌아가기 어렵습니다.
그러니 조금 번거롭더라도 꼭 한번 붙여보시길 권합니다.
깃허브 MCP 서버부터 연결해봅니다
가장 많이 쓰는 깃허브 연결부터 해보겠습니다. 준비물은 깃허브 개인 액세스 토큰(personal access token) 하나면 충분합니다.
토큰은 쉽게 말해 '내 계정을 대신 여는 열쇠' 같은 거라고 보시면 되구요. 이 열쇠를 Claude Code에게 건네주면, Claude Code가 제 저장소를 대신 열어볼 수 있게 됩니다.
발급 자체는 몇 번의 클릭이면 끝나니 겁먹지 않으셔도 됩니다.
먼저 터미널에서 아래 한 줄을 입력합니다. Claude Code가 설정 파일을 자동으로 만들어주기 때문에 직접 파일을 열 필요가 없습니다.
명령을 치면 토큰을 붙여넣으라는 안내가 나옵니다. 깃허브 설정의 Developer settings에서 발급한 토큰을 그대로 입력하면 되구요.
이때 토큰이 화면에 그대로 보이지 않아도 당황하지 마세요. 보안을 위해 일부러 가려서 표시되는 경우가 많거든요. 그냥 붙여넣고 엔터를 치면 정상적으로 처리됩니다.
⚠️ 여기서 자주 막힙니다 — 토큰 권한(scope)
여기서 자주 막히는 지점이 하나 있습니다. 토큰 권한(scope)을 너무 좁게 잡으면 저장소를 못 읽는 경우가 생기네요.
발급 화면에서 체크박스가 잔뜩 나오는데, 겁이 나서 아무것도 안 고르는 분들이 많습니다. 하지만 그렇게 하면 정작 필요한 데이터를 하나도 못 가져옵니다.
이슈나 코드를 읽으려면 repo 권한을 꼭 체크해야 합니다. 권한 설정을 빼먹으면 연결은 되지만 아무 데이터도 안 넘어옵니다. 이게 은근히 헷갈리는 부분인데요, 목록에는 멀쩡히 떠서 성공한 줄 알기 쉽거든요.
그래서 데이터가 안 온다면 가장 먼저 토큰 권한부터 의심해보시는 게 좋습니다.
연결이 끝나면 Claude Code에게 이렇게 말해볼 수 있습니다. "내 저장소의 최근 이슈 3개를 요약해줘"라고 하면 실제로 읽어옵니다.
명령어를 외울 필요 없이 평소 말하듯 부탁하면 되는 게 매력이구요. 복잡한 API 문서를 뒤질 일도 없어집니다.
💬 초반 5분의 값어치
솔직히 처음엔 토큰 발급 과정이 번거로웠습니다. 다만 한 번만 해두면 그 뒤로는 신경 쓸 일이 없어서, 초반 5분 투자할 가치는 충분하다고 느꼈습니다.
저처럼 명령어에 익숙하지 않은 분이라면 첫 시도에서 조금 헤맬 수도 있습니다. 그래도 안내 문구를 천천히 따라가면 누구나 해낼 수 있는 수준이니 안심하세요.
데이터베이스와 브라우저도 같은 방식으로 붙입니다
MCP의 진짜 장점은 여기서 나옵니다. 연결 방식이 도구마다 똑같아서 하나만 해보면 나머지는 복사·붙여넣기 수준입니다.
깃허브를 붙여봤다면 이미 절반은 배운 셈이거든요. 앞서 콘센트 비유가 왜 딱 맞는지 여기서 실감하게 됩니다.
데이터베이스는 주로 PostgreSQL(포스트그레스큐엘) 서버를 많이 씁니다. 접속 주소만 준비하면 아래처럼 붙일 수 있습니다.
접속 주소를 입력하는 칸이 나오면 DB 연결 문자열을 넣습니다. 이후 "회원 테이블에서 가입자 수를 세줘" 같은 요청을 자연어로 던질 수 있게 됩니다.
예전 같으면 SQL 문법을 검색해가며 한 줄씩 써야 했던 작업이죠. 그걸 말 한마디로 끝낼 수 있으니 진입 장벽이 확 낮아집니다.
브라우저 연결도 흥미롭습니다. Playwright(플레이라이트)라는 도구를 MCP로 붙이면, Claude Code가 실제 웹페이지를 열고 화면을 확인할 수 있습니다.
화면을 눈으로 보듯 읽어내니, 단순히 코드만 다루던 때와는 차원이 다릅니다.
이걸로 웹사이트 동작을 테스트하거나 화면을 캡처하는 작업을 맡길 수 있구요. 반복되는 클릭 작업을 대신 시키기에도 좋습니다.
예를 들어 로그인 화면이 잘 뜨는지 매번 손으로 확인하던 일을 자동으로 돌릴 수 있습니다. 지루한 반복 작업일수록 이 방식의 효과가 크게 느껴집니다.
💡 브라우저 MCP는 미리 깔아두세요
다만 브라우저 MCP는 설치 용량이 제법 큽니다. 처음 붙일 때 다운로드가 오래 걸릴 수 있으니 여유 있을 때 미리 설정해두길 권합니다.
급하게 필요할 때 설치가 안 끝나 발을 동동 구르는 상황은 피하는 게 좋겠죠. 저는 다른 작업을 하는 동안 백그라운드로 깔아두는 방식을 씁니다.
| 도구 | 연결 명령 | 이런 걸 시킬 수 있어요 |
|---|---|---|
| 깃허브 | claude mcp add github |
저장소 최근 이슈 읽기·요약 |
| 데이터베이스 (PostgreSQL) |
claude mcp add postgres |
자연어로 테이블 조회 ("가입자 수 세줘") |
| 브라우저 (Playwright) |
MCP로 별도 설치 (용량 큼·미리 준비) |
웹페이지 열기·동작 테스트·화면 캡처 |
💬 셋 중 뭐가 제일 유용했나요?
제가 셋 다 붙여보니, 데이터베이스 연결이 체감상 가장 유용했습니다. 쿼리 문법을 몰라도 원하는 데이터를 말로 꺼내 쓸 수 있다는 점이 비개발자에게는 특히 큰 무기가 되겠더군요.
물론 어떤 도구가 제일 유용한지는 하는 일마다 다를 겁니다. 그러니 세 가지를 다 붙여보고 자기 작업에 맞는 걸 찾아보시길 추천합니다.
제대로 붙었는지 확인하고 실전에 씁니다
붙였으면 잘 연결됐는지 확인하는 습관이 중요합니다. 터미널에 아래 명령을 치면 현재 연결된 MCP 서버 목록이 한눈에 나옵니다.
확인 없이 바로 작업을 시키면, 문제가 생겼을 때 원인을 찾기가 훨씬 어려워지거든요. 그러니 붙인 직후 목록부터 확인하는 걸 습관으로 삼으시면 좋습니다.
여기에 방금 추가한 github, postgres 같은 이름이 보이면 성공입니다. 목록에 이름이 안 뜬다면 설정이 저장되지 않은 것이니 추가 명령을 다시 실행해야 합니다.
가끔 오타 하나 때문에 저장이 안 되는 경우도 있으니 명령어를 천천히 다시 확인해보세요. 이름만 제대로 떠도 절반은 성공한 셈입니다.
연결은 됐는데 작동이 이상할 때도 있습니다. 대부분 토큰 만료나 권한 부족이 원인이네요.
특히 토큰은 유효 기간이 정해진 경우가 많아서, 시간이 지나면 조용히 만료되기도 합니다. 어제까지 잘 되던 게 오늘 안 된다면 이 경우를 먼저 의심해보세요.
💡 안 될 땐 지웠다 다시 붙이기
이럴 땐 해당 서버를 지우고 다시 붙이는 게 가장 빠릅니다. remove 명령으로 지운 뒤 add로 재연결하면 깔끔하게 해결됩니다.
이것저것 원인을 파고들기보다, 한 번 밀고 새로 붙이는 편이 시간을 아끼는 경우가 많거든요. 물론 반복해서 같은 문제가 난다면 그땐 토큰 설정을 근본부터 다시 살펴봐야 합니다.
실전에서는 여러 MCP를 조합할 때 힘이 세집니다. 깃허브에서 이슈를 읽어와 데이터베이스를 고치고 브라우저로 결과를 확인하는 흐름을 한 번에 맡길 수 있습니다.
각각 따로 하던 일을 하나의 요청으로 이어붙이는 순간, 진짜 자동화의 맛을 보게 됩니다. 이 조합의 가능성은 쓰면 쓸수록 넓어집니다.
⚠️ 서버는 두세 개만 남기세요
한 가지 당부하자면, 필요 없는 서버까지 다 붙이진 마시길 바랍니다. 서버가 많아질수록 Claude Code가 헷갈릴 수 있어서, 실제로 쓰는 두세 개만 남기는 편이 훨씬 쾌적했습니다.
도구는 많다고 무조건 좋은 게 아니라, 손에 익은 것을 잘 쓰는 게 더 중요하거든요. 처음엔 하나씩 붙여 익숙해진 뒤, 정말 필요한 것만 곁에 두는 방식을 권해드립니다.
✍️ 마치며
MCP는 Claude Code를 '말만 하는 조수'에서 '직접 움직이는 손발'로 바꿔주는 연결 고리입니다. 깃허브 하나만 제대로 붙여보면 데이터베이스도 브라우저도 같은 요령으로 이어지니, 오늘 딱 5분만 투자해 첫 서버를 붙여보세요.
붙인 뒤엔 꼭 claude mcp list로 확인하고, 안 되면 지웠다 다시 붙이며, 정말 필요한 두세 개만 곁에 두기 — 이 세 가지만 기억하면 충분합니다.
'AI 툴 문제 해결' 카테고리의 다른 글
| Claude Code 플랜 모드 사용법, 코드 수정 전 계획서 받는 법 (0) | 2026.07.21 |
|---|---|
| Claude Sonnet 5 달라진 점과 상위 모델 선택 기준 (0) | 2026.07.21 |
| Claude Code 터미널 없이 쓰기, 데스크톱 앱·VS Code 확장 가이드 (0) | 2026.07.21 |
| Claude Code 응답이 느리거나 멈출 때 해결법 (0) | 2026.04.13 |
| Claude Code에서 같은 오류가 반복될 때 탈출하는 방법 (0) | 2026.04.12 |
