Claude Desktop + MCP 실전: 데이터베이스, 파일 시스템, Web 연결 완전 가이드

AI 비서가 더 강력한 도구가 되려면 외부 데이터와 시스템에 접근해야 합니다. 이 튜토리얼에서는 Anthropic의 MCP(Model Context Protocol)를 활용해 Claude Desktop을 데이터베이스, 파일 시스템, 웹에 연결하는 방법을 처음부터 설명합니다. HolySheep AI를 사용하면 모든 주요 AI 모델을 단일 API 키로 통합 관리할 수 있습니다.

MCP란 무엇인가?

MCP는 AI 모델이 외부 도구와 데이터를 안전하게 활용할 수 있도록 설계된 개방형 프로토콜입니다. 마치 스마트폰에 앱을 설치하듯, Claude Desktop에 다양한 연결 기능을 추가할 수 있습니다.

• 파일 시스템 접근: 로컬 폴더의 문서를 읽고 수정
• 데이터베이스 연결: MySQL, PostgreSQL, SQLite 등 직접 查询
• 웹 검색: 실시간 정보 조회 및 웹 페이지 분석

사전 준비

1단계: HolySheep AI API 키 발급

먼저 HolySheep AI에서 API 키를 발급받아야 합니다. HolySheep AI는 지금 가입하면 무료 크레딧을 제공하며, 해외 신용카드 없이도 로컬 결제가 지원됩니다.

1. HolySheep AI 웹사이트 방문 후 회원가입
2. 대시보드에서 API Keys 메뉴 선택
3. "새 키 생성" 클릭하여 API 키 복사

2단계: Claude Desktop 설치

Claude Desktop 공식 웹사이트에서 운영체제에 맞는 버전을 다운로드하여 설치합니다. 설치 완료 후 애플리케이션을 실행하여 초기 설정을 완료합니다.

3단계: Node.js 설치 확인

MCP 서버를 실행하려면 Node.js가 필요합니다. 터미널에서 다음 명령어로 설치 여부를 확인하세요.

node --version
npm --version

아직 설치하지 않았다면 Node.js 공식 웹사이트에서 LTS 버전을 다운로드하세요.

MCP 서버 설치 및 설정

1단계: claude_desktop_config.json 파일 생성

Claude Desktop의 환경설정 폴더에 설정 파일을 만들어야 합니다. 파일 위치는 다음과 같습니다:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

[참고: 터미널에서 mkdir -p 명령어로 폴더를 먼저 생성해야 할 수 있습니다]

2단계: HolySheep AI 연결 설정 추가

생성한 설정 파일에 다음 내용을 입력하세요. HolySheep AI의 엔드포인트를 통해 Claude 모델에 접근합니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourusername/Documents"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"]
    }
  },
  "globalShortcut": "Cmd+Shift+C",
  "apiKey": "YOUR_HOLYSHEEP_API_KEY",
  "baseURL": "https://api.holysheep.ai/v1"
}

중요: YOUR_HOLYSHEEP_API_KEY 부분을 HolySheep AI에서 발급받은 실제 API 키로 교체하세요. /Users/yourusername/Documents 부분도 실제 경로로 변경해야 합니다.

파일 시스템 연결 설정

Claude Desktop에서 특정 폴더의 파일을 읽고 쓸 수 있게 설정합니다.

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

이렇게 설정하면 Claude Desktop에서 지정한 두 폴더 내의 파일에 접근할 수 있습니다. 설정 후 Claude Desktop을 완전히 종료하고 다시 실행하면 변경사항이 적용됩니다.

데이터베이스 연결 설정

PostgreSQL 연결 예시

PostgreSQL 데이터베이스에 연결하려면 관련 MCP 서버를 설치하고 설정합니다.

{
  "mcpServers": {
    "postgresql": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost:5432/mydb"]
    }
  }
}

연결 문자열 형식: postgresql://사용자:비밀번호@호스트:포트/데이터베이스이름

SQLite 연결 예시

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/your/database.db"]
    }
  }
}

[참고: 데이터베이스 파일 경로는 절대경로로 지정해야 합니다]

웹 검색 연결 설정

Brave Search API를 사용하면 Claude Desktop에서 실시간 웹 검색이 가능합니다.

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your_brave_api_key_here"
      }
    }
  }
}

Brave Search API 키는 Brave 공식 웹사이트에서 무료로 발급받을 수 있습니다.

실전 활용 예시

프로젝트 문서 자동 분석

파일 시스템 연결이 완료되면 Claude에게 다음과 같이 요청할 수 있습니다:

• "Projects 폴더의 모든 Python 파일을 찾아 함수 목록을 만들어줘"
• "Documents 폴더의 report.txt 내용을 요약해줘"
• "Projects/src 폴더에서 버그가 있을 것 같은 파일을 찾아줘"

데이터베이스 직접查询

데이터베이스 연결 후에는 자연어로 데이터 조회가 가능합니다:

• "사용자 테이블에서 최근 7일内有활동한 사용자를 알려줘"
• "주문 데이터 중 금액이 100만원 이상인 주문의 평균을 계산해줘"
• "products 테이블의 구조를 설명해줘"

실시간 정보 조회

웹 검색 연결 시:

• "오늘 날씨를 알려줘"
• "최신 AI 트렌드 기사를 찾아줘"
• "특정 기술의 최신 문서를 검색해줘"

자주 발생하는 오류 해결

오류 1: "command not found: npx"

문제: npx 명령어를 찾을 수 없다는 오류가 발생합니다.

해결: Node.js가 올바르게 설치되지 않았거나 PATH에 등록되지 않은 상태입니다. Node.js를 다시 설치하거나 터미널을 새로 열고 source ~/.bashrc 또는 source ~/.zshrc를 실행하세요. 설치 확인은 which node와 which npm 명령어로 할 수 있습니다.

오류 2: "Connection refused" 또는 타임아웃

문제: 데이터베이스나 API에 연결할 수 없습니다.

해결: 연결 문자열의 호스트, 포트, 자격증명을 다시 확인하세요. 방화벽이 해당 포트를 차단하고 있는지 확인하고, 데이터베이스 서버가 실행 중인지 검증하세요. 로컬 데이터베이스의 경우 pg_isready 또는 mysqladmin ping 명령어로 상태를 확인할 수 있습니다.

오류 3: "Permission denied" 파일 접근 오류

문제: 지정한 폴더나 파일에 접근할 수 없습니다.

해결: 폴더 권한을 확인하세요. macOS에서는 chmod 755 /path/to/folder로 권한을 부여할 수 있습니다. 설정 파일에서 지정한 경로가 존재하고 정확한지 다시 한 번 점검하세요. 경로에 특수문자나 한글 문자가 포함된 경우 인코딩 문제가 발생할 수 있습니다.

오류 4: MCP 서버가 목록에 표시되지 않음

문제: Claude Desktop을 다시 실행해도 MCP 서버가 로드되지 않습니다.

해결: claude_desktop_config.json 파일의 JSON 문법을 검증하세요. 유효하지 않은 JSON은 서버가 로드되지 않습니다. JSONLint 웹사이트나 cat ~/.config/Claude/claude_desktop_config.json | python3 -m json.tool 명령어로 검증할 수 있습니다. 파일 경로도 정확하게 지정했는지 확인하세요.

오류 5: API 키 관련 오류

문제: API 호출 시 인증 오류가 발생합니다.

해결: HolySheep AI 대시보드에서 API 키가 활성화되어 있는지, 사용량 한도에 도달하지 않았는지 확인하세요. 키가 올바른 형식인지, 앞뒤에 공백이 없이 정확히 복사되었는지 점검하세요. 키를 재발급받은 경우 Claude Desktop 설정의 API 키도 함께 업데이트해야 합니다.

확장: 여러 MCP 서버 동시 사용

한 번의 설정으로 다양한 소스를 동시에 연결할 수 있습니다.

{
  "mcpServers": {
    "filesystem-projects": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Projects"]
    },
    "filesystem-docs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"]
    },
    "postgresql": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost:5432/appdb"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "BSArinXXXXXXXXXXXXXXXXXXXXXX"
      }
    }
  }
}

이렇게 설정하면 Claude Desktop에서 파일 시스템 查询, 데이터베이스 조회의に加え 웹 검색까지 한 세션 내에서 모두 활용할 수 있습니다.

결론

MCP를 활용하면 Claude Desktop이 단순한 대화 AI를 넘어 다양한 데이터 소스와 연동되는 강력한 작업 어시스턴트로 변신합니다. HolySheep AI를 사용하면Claude를 포함한 모든 주요 모델을 단일 API 키로 관리할 수 있어 인프라 관리가 훨씬 간단해집니다.

시작하기 어려우셨나요? HolySheep AI의 자세한 문서와 커뮤니티 지원을 통해 첫 번째 MCP 연결을 성공시켜 보세요.

👉 HolySheep AI 가입하고 무료 크레딧 받기