Claudxk 가이드 - AI 코딩 어시스턴트 시작하기

MCP 서버

Claude에게 추가 능력을 붙여주는 확장 기능이에요.

MCP란 무엇인가요?

MCP (Model Context Protocol)는 Claude에게 추가 능력을 붙여주는 확장 기능이에요. 쉽게 말해, Claude가 더 많은 곳(파일, 데이터베이스, 웹 등)에 접근할 수 있게 해주는 "플러그인" 같은 거예요.

내 컴퓨터 파일

파일과 폴더를 읽고 수정할 수 있어요.

데이터베이스

데이터베이스에서 직접 데이터를 가져올 수 있어요.

Git 연동

코드 변경 이력 보기, 저장, 분기 관리 등이 가능해요.

웹 연결

외부 웹사이트나 서비스에서 실시간 데이터를 가져와요.

Claude Code vs Claude Desktop

기능	Claude Code	Claude Desktop
로컬 파일 접근	기본 제공	MCP 필요
터미널 명령어 실행	기본 제공	MCP 필요
Git 통합	기본 제공	MCP 필요
웹 검색	기본 제공	MCP 필요
GUI 인터페이스	터미널 기반	기본 제공

팁: Claude Code는 이미 내 컴퓨터 파일에 접근할 수 있어서 MCP가 꼭 필요하진 않아요. 반면 Claude Desktop(앱 버전)에서 같은 기능을 쓰려면 MCP 설정이 필요해요.

Claude Code에서 MCP 서버 추가

Claude Code에서는 claude mcp add 명령으로 MCP 서버를 추가할 수 있어요. 3가지 연결 방식이 있어요.

HTTP 서버 (추천)

원격 MCP 서버에 연결하는 권장 방법이에요.

claude mcp add --transport http notion https://mcp.notion.com/mcp

인증이 필요한 서버는 /mcp 명령으로 OAuth 로그인하세요.

SSE 서버 (레거시)

SSE 방식은 deprecated예요. 가능하면 HTTP를 사용하세요.

claude mcp add --transport sse asana https://mcp.asana.com/sse

로컬 stdio 서버

로컬에서 프로세스로 실행하는 방식이에요.

claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable -- npx -y airtable-mcp-server

서버 관리

claude mcp list # 목록 확인

claude mcp get github # 상세 정보

claude mcp remove github # 제거

세션 중에는 /mcp 명령으로 상태를 확인할 수 있어요.

MCP Tool Search

MCP 도구가 많아지면 컨텍스트 창의 10%를 넘게 돼요. 그러면 Tool Search가 자동으로 활성화되어, 필요한 도구만 로드해요.

설정	동작
`auto` (기본)	10% 초과 시 자동 활성화
`true`	항상 활성화
`false`	비활성화 (모든 도구 로드)

Claude Desktop에서 MCP 설정하기

1단계: 설정 파일 열기

Claude Desktop의 MCP 설정 파일을 열어요.

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

파일이 없다면 새로 만드세요.

2단계: 파일시스템 MCP 서버 추가

내 컴퓨터 파일에 접근하게 하려면 아래 설정을 넣어요.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/사용자이름/Documents"
      ]
    }
  }
}

/Users/사용자이름/Documents 부분을 실제 작업 폴더 위치로 바꿔주세요.

3단계: Git MCP 서버 추가 (선택)

Git 기능도 쓰고 싶다면 아래 설정을 추가해요.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/사용자이름/Documents"]
    },
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/Users/사용자이름/프로젝트폴더"]
    }
  }
}

4단계: Claude Desktop 재시작

설정을 저장한 후 Claude Desktop을 완전히 종료했다가 다시 실행해요.

1Command + Q로 Claude Desktop 종료

2Claude Desktop 다시 실행

3설정 아이콘에서 MCP 서버 연결 확인

문제 해결

MCP 서버가 연결되지 않아요

설정 파일에 오타가 없는지 확인하세요.
Node.js가 깔려 있는지 확인: node --version
Claude Desktop을 완전히 종료한 뒤 다시 실행하세요.
터미널에서 직접 실행해서 에러 메시지가 뜨는지 확인하세요.

파일을 찾을 수 없다고 해요

설정 파일의 폴더 위치가 정확한지 확인하세요.
~ 대신 전체 경로(/Users/이름/...)를 써보세요.
해당 폴더를 열 수 있는 권한이 있는지 확인하세요.

npx/uvx 명령어를 찾을 수 없어요

npx: Node.js가 필요해요 - brew install node로 설치
uvx: uv가 필요해요 - brew install uv로 설치