Claude Desktop MCP Server 구축 완전 가이드: 로컬 도구 확장 실전

안녕하세요, 저는 HolySheep AI의 기술 블로그 작가입니다. 이번 글에서는 Claude Desktop에 나만의 도구를 추가할 수 있게 해주는 MCP Server를 처음부터 만들어보겠습니다. 프로그래밍을 해본 적이 없는 분도 따라할 수 있도록 쉬운言葉で 설명할게요.

MCP Server가 뭔가요?

쉽게 말하면, Claude Desktop이 내 컴퓨터에 있는 파일을 읽거나 명령어를 실행할 수 있게 해주는 연결 다리입니다. 예를 들어:

• 내 폴더 안의 파일을 읽어달라
• 특정 프로그램을 실행해달라
• 계산 결과를 파일에 저장해달라

이런 작업들을 Claude Desktop이 할 수 있게 만드는 거예요.

준비물

• Node.js — 프로그래밍 도구 (무료, 공식 사이트에서 다운로드)
• Claude Desktop — Anthropic에서 만든 AI 도구
• HolySheep AI 계정 — 지금 가입하고 무료 크레딧 받기

1단계: 프로젝트 폴더 만들기

먼저 내 컴퓨터에 작업할 공간을 만들어야 합니다. 터미널(명령프롬프트)을 열고 다음 명령어를 입력하세요:

mkdir claude-mcp-server
cd claude-mcp-server
npm init -y

실행 결과 확인: 폴더가 생기고 "package.json"이라는 파일이 만들어질 거예요.

2단계: 필요한 도구 설치하기

npm init으로 만든 프로젝트에 MCP Server를 만들기 위한 도구를 추가합니다:

npm install @modelcontextprotocol/sdk @modelcontextprotocol/server-filesystem zod

이 명령어는 세 가지 도구를 한꺼번에 설치합니다:

• @modelcontextprotocol/sdk — MCP Server를 만들기 위한 기본 도구
• @modelcontextprotocol/server-filesystem — 파일을 읽고 쓰는 도구
• zod — 데이터가 올바른지 확인하는 도구

3단계: MCP Server 코드 작성하기

이제 실제로 작동하는 코드를 만들어보겠습니다. "server.js"라는 새 파일을 만드세요:

const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
const {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} = require('@modelcontextprotocol/sdk/types.js');
const { z } = require('zod');

// HolySheep AI API 설정
const HOLYSHEEP_API_KEY = process.env.HOLYSHEEP_API_KEY || 'YOUR_HOLYSHEEP_API_KEY';
const HOLYSHEEP_BASE_URL = 'https://api.holysheep.ai/v1';

// 사용자가 요청할 수 있는 도구 목록 정의
const TOOLS = [
  {
    name: 'read_file',
    description: '파일 내용을 읽습니다. 파일 경로를 입력하면 내용을 보여줍니다.',
    inputSchema: {
      type: 'object',
      properties: {
        path: {
          type: 'string',
          description: '읽을 파일 경로 (예: /Users/사용자/ documents/test.txt)',
        },
      },
      required: ['path'],
    },
  },
  {
    name: 'write_file',
    description: '파일을 새로 만들거나 내용을 덮어씁니다.',
    inputSchema: {
      type: 'object',
      properties: {
        path: {
          type: 'string',
          description: '파일 경로',
        },
        content: {
          type: 'string',
          description: '파일 안에 넣을 내용',
        },
      },
      required: ['path', 'content'],
    },
  },
  {
    name: 'list_directory',
    description: '폴더 안에 있는 파일과 폴더 목록을 보여줍니다.',
    inputSchema: {
      type: 'object',
      properties: {
        path: {
          type: 'string',
          description: '목록을 볼 폴더 경로',
        },
      },
      required: ['path'],
    },
  },
];

// 서버 만들기
const server = new Server(
  {
    name: 'holy-shee-mcp-server',
    version: '1.0.0',
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// 도구 목록 보여주기
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return { tools: TOOLS };
});

// 도구 실행하기
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  try {
    if (name === 'read_file') {
      const fs = require('fs').promises;
      const content = await fs.readFile(args.path, 'utf-8');
      return {
        content: [
          {
            type: 'text',
            text: 파일 내용:\n${content},
          },
        ],
      };
    }

    if (name === 'write_file') {
      const fs = require('fs').promises;
      await fs.writeFile(args.path, args.content, 'utf-8');
      return {
        content: [
          {
            type: 'text',
            text: 파일 저장 완료: ${args.path},
          },
        ],
      };
    }

    if (name === 'list_directory') {
      const fs = require('fs').promises;
      const items = await fs.readdir(args.path, { withFileTypes: true });
      const list = items
        .map((item) => ${item.isDirectory() ? '📁' : '📄'} ${item.name})
        .join('\n');
      return {
        content: [
          {
            type: 'text',
            text: ${args.path} 내용:\n${list},
          },
        ],
      };
    }

    throw new Error(도구를 찾을 수 없습니다: ${name});
  } catch (error) {
    return {
      content: [
        {
          type: 'text',
          text: 오류 발생: ${error.message},
        },
      ],
      isError: true,
    };
  }
});

// 서버 시작
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error('HolySheep MCP Server 시작됨!');
}

main().catch(console.error);

4단계: Claude Desktop 설정하기

이제 Claude Desktop에게 우리 서버를 사용하라고 알려줘야 합니다.

설정 파일 위치 찾기

Mac의 경우:

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

Windows의 경우:

%APPDATA%\Claude\claude_desktop_config.json

설정 파일 내용

해당 파일을 텍스트 편집기로 열고 이렇게 수정하세요:

{
  "mcpServers": {
    "holy-sheep-server": {
      "command": "node",
      "args": ["/absolute/path/to/your/server.js"],
      "env": {
        "HOLYSHEEP_API_KEY": "YOUR_HOLYSHEEP_API_KEY"
      }
    }
  }
}

주의: "/absolute/path/to/your/server.js" 부분을 실제 파일 경로로 바꿔야 합니다. 예를 들어:

• Mac: /Users/사용자이름/projects/claude-mcp-server/server.js
• Windows: C:\Users\사용자\projects\claude-mcp-server\server.js

5단계: Claude Desktop 재시작

설정을 저장한 후 Claude Desktop을 완전히 닫고 다시 실행하세요.

동작 확인 방법:

1. Claude Desktop에서 도구 아이콘(🔧)을 찾아보세요
2. 나만의 서버가 보이면 성공!
3. "read_file"이나 "list_directory" 도구를试着 사용해보세요

HolySheep AI API 연동하기

저는 실제로 HolySheep AI의 API를 사용해서 더 강력한 MCP Server를 만들어보았습니다. 다음은 HolySheep AI의 Claude 모델을 호출하는 예제예요:

const HOLYSHEEP_API_KEY = 'YOUR_HOLYSHEEP_API_KEY';
const HOLYSHEEP_BASE_URL = 'https://api.holysheep.ai/v1';

async function askClaude(prompt) {
  const response = await fetch(${HOLYSHEEP_BASE_URL}/chat/completions, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': Bearer ${HOLYSHEEP_API_KEY},
    },
    body: JSON.stringify({
      model: 'claude-sonnet-4-20250514',
      messages: [{ role: 'user', content: prompt }],
      max_tokens: 1000,
    }),
  });

  const data = await response.json();
  return data.choices[0].message.content;
}

// 사용 예시
askClaude('안녕하세요!').then(console.log);

HolySheep AI 가격 정보 (2025년 6월 기준):

• Claude Sonnet 4.5: $15/MTok (약 15원/1,000토큰)
• Claude Opus 4: $75/MTok (약 75원/1,000토큰)
• DeepSeek V3.2: $0.42/MTok (약 0.5원/1,000토큰) — 초저렴

실전 예제: 계산기 MCP Server

파일을 읽고 쓰는 것 말고 다른 것도 만들어보겠습니다. 계산기 도구를 추가해볼게요:

// TOOLS 배열에 추가
{
  name: 'calculate',
  description: '수학 계산을 합니다.',
  inputSchema: {
    type: 'object',
    properties: {
      expression: {
        type: 'string',
        description: '수학 식 (예: 2 + 2, 10 * 5, 100 / 4)',
      },
    },
    required: ['expression'],
  },
},

// CallToolRequestHandler에 추가
if (name === 'calculate') {
  try {
    // eval 대신 Function 사용 (더 안전)
    const safeEval = new Function(return ${args.expression});
    const result = safeEval();
    return {
      content: [
        {
          type: 'text',
          text: ${args.expression} = ${result},
        },
      ],
    };
  } catch (error) {
    return {
      content: [
        {
          type: 'text',
          text: 계산 오류: ${error.message},
        },
      ],
      isError: true,
    };
  }
}

자주 발생하는 오류 해결

오류 1: "command not found: npm"

원인: Node.js가 설치되지 않았거나 경로가 설정되지 않음

해결 방법:

1. https://nodejs.org/에서 LTS 버전 다운로드
2. 설치 후 터미널을 새로 열고 node --version 입력
3. 버전 번호가 보이면 설치 성공

# Mac/Linux에서 경로 확인
echo $PATH

Node.js 경로 추가 (Mac)
export PATH="/usr/local/bin:$PATH"

재설치
brew install node

오류 2: "Cannot find module '@modelcontextprotocol/sdk'"

원인: npm 패키지가 설치되지 않음

해결 방법:

# 프로젝트 폴더로 이동
cd claude-mcp-server

패키지 다시 설치
npm install @modelcontextprotocol/sdk @modelcontextprotocol/server-filesystem zod

설치 확인
ls node_modules | grep modelcontextprotocol

오류 3: "File path not found" 또는 권한 오류

원인: 파일 경로가 잘못되었거나 읽기 권한이 없음

해결 방법:

# Mac에서 경로 확인하고 권한 부여
pwd  # 현재 경로 확인
chmod 755 /path/to/your/file.txt

Windows에서 관리자 권한으로 실행
시작 메뉴 → PowerShell 우클릭 → 관리자로 실행

오류 4: Claude Desktop이 서버를 인식하지 못함

원인: 설정 파일 형식 오류 또는 경로 오류

해결 방법:

# 1. 설정 파일 JSON 유효성 검사
JSONlint.com에서 확인하거나 터미널에서:
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

2. 서버 경로 절대경로로 변경
상대경로 대신 완전한 경로 사용
예: ./server.js → /Users/username/projects/claude-mcp-server/server.js

3. Claude Desktop 완전 종료 후 재시작
Mac: Command + Q로 완전히 종료
Ctrl + R로 다시 실행

오류 5: HolySheep API 호출 시 401 Unauthorized

원인: API 키가 없거나 잘못됨

해결 방법:

# 1. HolySheep AI 대시보드에서 API 키 확인
https://www.holysheep.ai/register → Dashboard → API Keys

2. 환경 변수로 설정
export HOLYSHEEP_API_KEY="sk-holysheep-your-real-key"

3. 또는 직접 코드에 입력 (테스트용)
const HOLYSHEEP_API_KEY = 'sk-holysheep-your-real-key';

4. 키가 sk-로 시작하는지 확인

성능 최적화 팁

저는 실제로 MCP Server를 운영하면서 여러 가지 최적화를 해보았습니다.

• 캐시 사용: 같은 파일을 여러 번 읽지 말고 결과를 저장하세요
• 비동기 처리: 파일 작업을 async/await로 처리하면 더 빨라요
• 요청 제한: HolySheep AI는 분당 요청 수 제한이 있으므로 10ms 딜레이 추가

// 최적화된 파일 읽기 (캐시 포함)
const fileCache = new Map();
const CACHE_TTL = 60000; // 1분

async function readFileCached(path) {
  const cached = fileCache.get(path);
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.content;
  }
  
  const fs = require('fs').promises;
  const content = await fs.readFile(path, 'utf-8');
  fileCache.set(path, { content, timestamp: Date.now() });
  return content;
}

마무리

축하합니다! 이제 나만의 Claude Desktop MCP Server를 만들 수 있게 되었어요. 이 튜토리얼에서 배운 것:

• MCP Server 기본 구조 이해하기
• 파일 읽기/쓰기 도구 만들기
• 계산기 도구 추가하기
• HolySheep AI API 연동하기
• 자주 발생하는 오류 해결하기

HolySheep AI는 해외 신용카드 없이도 로컬 결제가 가능해서 개발자 분들께 정말方便的이에요. Claude, GPT, Gemini, DeepSeek 등 다양한 모델을 하나의 API 키로管理할 수 있어요.

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