GameDrop MCP Server (gamedrop-mcp)

GameDrop MCP 서버는 스팀(Steam), 에픽게임즈 스토어(Epic Games Store), GOG, 험블 번들(Humble Store) 등 다양한 플랫폼의 무료 배포 게임, 할인율 순 게임 할인 정보 검색, 플랫폼별 가격 실시간 비교 및 최저가 조회, 그리고 상세 게임 정보를 인공지능 에이전트(Kakao PlayMCP, Claude Desktop, ChatGPT MCP 등)에게 실시간으로 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다.

주요 기능 및 MCP 도구 (Tools)

본 서버는 다음 5가지 핵심 MCP 도구(Tool)를 노출합니다:

1. gameDropFreeGames: 현재 주요 플랫폼에서 무료로 배포되고 있는 게임 정보 및 구매/다운로드 링크 목록을 실시간으로 가져옵니다. (에픽게임즈 스토어 포함)

   • 파라미터: platform (all | steam | epic | gog)

2. gameDropDiscounts: 플랫폼별 현재 할인 중인 게임의 정상가, 할인가, 할인율 및 다이렉트 구매 링크 목록을 정렬해 반환합니다.

   • 파라미터: platform (all | steam | epic | gog), minDiscount (최소 할인율 %, 기본값: 50), limit (조회 개수, 기본값: 20)

3. gameDropSearch: 게임명(영문/한글 키워드)으로 게임의 ID 및 스토어별 최저가 정보를 빠르게 검색합니다.

   • 파라미터: keyword (검색어)

4. gameDropComparePrice: 입력받은 게임 타이틀에 대해 지원되는 모든 온라인 스토어(Steam, GOG, Epic, Humble 등)의 판매 가격을 실시간으로 비교하여 원화(KRW)로 정렬하고, 가장 저렴한 최저가 스토어 정보를 반환합니다.

   • 파라미터: title (게임 타이틀)

5. gameDropGameInfo: 스팀 API 데이터를 실시간으로 파싱하여 게임의 상세 소개 설명(한글화 우선 제공), 개발사, 퍼블리셔, 출시일, 장르(태그), 가격을 포괄적으로 반환합니다.

   • 파라미터: title (게임 타이틀)

Related MCP server: MCP Shop Server

환경 변수 설정 (.env)

프로젝트 루트에 .env 파일을 생성하고 아래 형식을 참고하여 설정합니다:

# HTTP 서버 포트 (Streamable HTTP 모드일 때만 적용됨, 기본값: 3000)
PORT=3000

# 트랜스포트 기본 모드 (sse 또는 stdio)
TRANSPORT=sse

# (선택 사항) 캐싱 성능 향상을 위한 Redis 서버 설정
# REDIS_URL=redis://localhost:6379

# (선택 사항) IsThereAnyDeal API 연동 시 필요한 API Key
ITAD_API_KEY=

로컬 개발 및 실행

1. 의존성 패키지 설치

npm install

2. 개발 모드로 실행 (핫 리로드)

npm run dev

3. TypeScript 컴파일 빌드

npm run build

4. 빌드된 프로덕션 서버 시작

npm run start

Docker 컨테이너 실행 및 빌드

이 프로젝트는 Docker 컨테이너 환경을 완벽하게 지원합니다.

Docker 단독 빌드 및 실행

# 1. Docker 이미지 빌드
docker build -t gamedrop-mcp .

# 2. 컨테이너 백그라운드 기동 (3000번 포트 연결)
docker run -d -p 3000:3000 --name gamedrop-mcp-server --env PORT=3000 gamedrop-mcp

Docker Compose 환경 실행 (Redis 캐시 포함)

docker-compose up -d --build

실행 후 http://localhost:3000/health 에 접속하여 정상 동작(Health Check) 여부를 확인할 수 있습니다.

MCP 플랫폼별 등록 및 사용법

1. Kakao PlayMCP (Streamable HTTP 기반 등록)

PlayMCP는 최신 MCP SDK의 Streamable HTTP 프로토콜을 사용해 MCP 서버를 등록할 수 있습니다.

• MCP Endpoint URL: http://<서버-도메인-또는-IP>:3000/mcp

• HTTP Method: GET/POST/DELETE (단일 /mcp 엔드포인트에서 모두 처리)

2. Claude Desktop (stdio 기반 등록)

Claude Desktop App의 MCP 설정 파일(claude_desktop_config.json)을 다음과 같이 편집하여 추가합니다:

• Windows 경로: %APPDATA%\Claude\claude_desktop_config.json

• macOS 경로: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "gamedrop-mcp": {
      "command": "node",
      "args": ["C:/absolute/path/to/gamedrop-mcp/build/src/index.js", "--transport=stdio"],
      "env": {
        "ITAD_API_KEY": ""
      }
    }
  }
}

3. ChatGPT MCP (stdio/Streamable HTTP 기반 등록)

사용하시는 ChatGPT MCP 커넥터 클라이언트의 지침에 따라 stdio 명령을 추가하거나, 실행 중인 Streamable HTTP 서비스 URL(http://<서버-도메인-또는-IP>:3000/mcp)을 기입하여 연동합니다.

아키텍처 및 복구력 (Resilience) 설계

• 안전한 로깅: stdio 모드로 구동될 때 stdout으로 로그가 유출되면 JSON-RPC 직렬화 규격이 손상됩니다. GameDrop MCP는 실행 모드를 감지하여 stdio 모드에서는 모든 시스템 로그를 stderr로 안전하게 우회 출력을 적용했습니다.

• 예외 복구력: Zod 스키마로 들어오는 인풋을 사전에 엄격히 검증하며, 외부 API 연동 에러가 발생해도 전체 서버의 다운타임으로 이어지지 않고 상세한 에러 원인을 JSON 결과 구조에 녹여 반환합니다.

• 이중 캐싱 시스템: ioredis를 지원하여 분산 서버나 컨테이너 환경에서는 Redis를 사용하여 부하를 덜고, Redis가 감지되지 않거나 연결 에러가 발생할 시 로컬 메모리-TTL 캐시 방식으로 자동 대체되어 무중단 구동됩니다.

• 환율 동적 변환: CheapShark API의 모든 달러($) 가격은 오픈 환율 API를 통해 원화(KRW)로 실시간 환산하여 한눈에 쉽게 딜을 파악할 수 있게 가공합니다.