crypto-market-mcp-server

quanttraderkim/crypto-market-mcp-server

3.1

If you are the rightful owner of crypto-market-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Crypto Market MCP Server provides real-time cryptocurrency market information using the Binance API.

Crypto Market MCP Server

CoinGecko API를 활용하여 실시간 암호화폐 시장 정보를 제공하는 MCP(Model Context Protocol) 서버입니다.

🚀 주요 기능

1단계 (완료)

  • get_coin_price: 특정 암호화폐의 현재 가격 조회 (USDT 기준)
  • 원화 환산 지원 (고정 환율 1340원/달러)
  • 실시간 가격 정보 제공

2단계 (완료)

  • get_top_gainers: 24시간 급등 코인 TOP 10 조회
  • get_top_losers: 24시간 급락 코인 TOP 10 조회
  • get_market_overview: 전체 시장 요약 정보
  • 거래량 필터링 및 데이터 검증
  • 실시간 시장 분석

3단계 (완료)

  • get_kimchi_premium: 김치 프리미엄 계산 (업비트 vs 바이낸스)
  • 실시간 USD/KRW 환율 조회 (Yahoo Finance + Exchange Rate API)
  • 업비트 API 연동
  • 한국 특화 암호화폐 분석 기능

4단계 (완료)

  • get_fear_greed_index: 암호화폐 시장 공포&탐욕 지수
  • get_coin_dominance: BTC/ETH 시장 도미넌스 분석
  • Alternative.me API 연동
  • 고급 시장 분석 및 트렌드 해석

향후 구현 예정

  • 추가 기술적 지표 분석
  • 포트폴리오 최적화 기능

📋 기술 스택

  • 언어: Python 3.8+
  • 프레임워크: FastMCP
  • 주요 API: CoinGecko API (무료, 가입 불요, 한국 접근 가능)
  • 의존성: requests, fastmcp, yfinance

🛠️ 설치 및 실행

1. 의존성 설치

pip install -r requirements.txt

2. 로컬 개발 서버 실행

fastmcp dev main.py

3. 프로덕션 서버 실행

python main.py

📖 API 사용법

get_coin_price

특정 암호화폐의 현재 가격을 조회합니다.

매개변수:

  • symbol (str): 암호화폐 심볼 (예: "BTC", "ETH", "ADA")

반환값:

{
    "symbol": "BTCUSDT",
    "price": 43250.50,
    "price_krw": 57825000,
    "timestamp": "2025-09-26T10:30:00Z"
}

get_top_gainers

24시간 기준 가장 많이 상승한 암호화폐 목록을 조회합니다.

매개변수:

  • limit (int): 조회할 코인 개수 (기본값: 10, 최대: 20)

반환값:

{
    "title": "24시간 급등 코인 TOP 10",
    "timestamp": "2025-09-26T10:30:00Z",
    "gainers": [
        {
            "rank": 1,
            "symbol": "ASTUSDT",
            "price": 0.1250,
            "change_percent": 45.67,
            "volume_24h": 12500000
        }
    ]
}

get_top_losers

24시간 기준 가장 많이 하락한 암호화폐 목록을 조회합니다.

매개변수:

  • limit (int): 조회할 코인 개수 (기본값: 10, 최대: 20)

반환값:

{
    "title": "24시간 급락 코인 TOP 10",
    "timestamp": "2025-09-26T10:30:00Z",
    "losers": [
        {
            "rank": 1,
            "symbol": "XRPUSDT",
            "price": 0.5890,
            "change_percent": -12.45,
            "volume_24h": 8900000
        }
    ]
}

get_market_overview

전체 암호화폐 시장의 요약 정보를 제공합니다.

반환값:

{
    "title": "암호화폐 시장 현황",
    "timestamp": "2025-09-26T10:30:00Z",
    "market_summary": {
        "total_coins": 2000,
        "total_volume_24h": 45000000000,
        "avg_change_24h": 2.34,
        "coins_up": 1200,
        "coins_down": 800
    },
    "top_3_by_volume": [
        {"symbol": "BTCUSDT", "volume": 15000000000},
        {"symbol": "ETHUSDT", "volume": 8500000000},
        {"symbol": "BNBUSDT", "volume": 2100000000}
    ]
}

get_kimchi_premium

한국 거래소(업비트)와 바이낸스 간의 김치 프리미엄을 계산합니다.

매개변수:

  • symbols (str): 조회할 코인 심볼들 (쉼표로 구분, 예: "BTC,ETH,XRP")

반환값:

{
    "title": "김치 프리미엄 현황",
    "timestamp": "2025-09-26T10:30:00Z",
    "exchange_rate_info": {
        "rate": 1412.58,
        "source": "Yahoo Finance",
        "description": "1 USD = 1,412.58 KRW 기준으로 계산",
        "last_updated": "실시간"
    },
    "coins": [
        {
            "symbol": "BTC",
            "upbit_price_krw": 158371000,
            "binance_price_usd": 109577.87,
            "binance_price_krw": 154787502,
            "premium_percent": 2.32,
            "premium_amount_krw": 3583497,
            "status": "프리미엄",
            "calculation_detail": "업비트 158,371,000원 - 바이낸스 154,787,503원 = +3,583,497원 (+2.32%)"
        }
    ],
    "summary": {
        "avg_premium": 2.31,
        "max_premium": 2.32,
        "min_premium": 2.31,
        "calculation_note": "모든 계산은 실시간 환율 1,412.58원/달러 기준입니다"
    }
}

get_fear_greed_index

암호화폐 시장의 공포&탐욕 지수를 조회합니다.

반환값:

{
    "title": "암호화폐 공포&탐욕 지수",
    "timestamp": "2025-09-26T10:30:00Z",
    "current": {
        "value": 28,
        "classification": "공포",
        "description": "시장이 공포 상태입니다. 매수 기회일 수 있습니다."
    },
    "history": {
        "yesterday": {"value": 30, "classification": "공포"},
        "last_week": {"value": 53, "classification": "중립"},
        "last_month": {"value": 45, "classification": "중립"}
    },
    "trend_analysis": "지난 주 대비 하락세 (53 → 28), 시장 심리 악화 중",
    "interpretation": {
        "range_explanation": "0-24: 극도의 공포, 25-44: 공포, 45-55: 중립, 56-75: 탐욕, 76-100: 극도의 탐욕",
        "current_meaning": "현재 지수 28은 시장 참가자들이 다소 두려워하고 있음을 의미합니다"
    }
}

get_coin_dominance

비트코인과 이더리움의 시장 도미넌스를 계산합니다.

반환값:

{
    "title": "암호화폐 시장 도미넌스",
    "timestamp": "2025-09-26T10:30:00Z",
    "market_cap_info": {
        "total_market_cap_usd": 3500000000000,
        "data_source": "바이낸스 24시간 거래량 기반 추정"
    },
    "dominance": {
        "bitcoin": {
            "percentage": 58.5,
            "market_cap_usd": 2047500000000,
            "price_usd": 109577.87,
            "status": "지배적"
        },
        "ethereum": {
            "percentage": 12.8,
            "market_cap_usd": 448000000000,
            "price_usd": 3951.68,
            "status": "강세"
        },
        "others": {
            "percentage": 28.7,
            "market_cap_usd": 1004500000000,
            "description": "기타 알트코인들"
        }
    },
    "analysis": {
        "btc_dominance_level": "높음",
        "market_phase": "비트코인 강세장",
        "interpretation": "비트코인 도미넌스가 58.5%로 높아 비트코인 중심의 시장 상황입니다"
    }
}

사용 예시:

# Bitcoin 가격 조회
result = get_coin_price("BTC")

# Ethereum 가격 조회  
result = get_coin_price("ETH")

# 급등 코인 TOP 5 조회
result = get_top_gainers(5)

# 급락 코인 TOP 10 조회
result = get_top_losers()

# 시장 전체 요약
result = get_market_overview()

# 김치 프리미엄 조회 (BTC, ETH)
result = get_kimchi_premium("BTC,ETH")

# 김치 프리미엄 조회 (기본값: BTC,ETH,XRP)
result = get_kimchi_premium()

# 공포&탐욕 지수 조회
result = get_fear_greed_index()

# 코인 도미넌스 조회
result = get_coin_dominance()

🔧 API 정보

CoinGecko API

  • 기본 URL: https://api.coingecko.com/api/v3
  • 엔드포인트:
    • /simple/price - 단일 코인 가격 조회
    • /coins/markets - 시장 데이터 조회
    • /global - 글로벌 시장 데이터
  • Rate Limit: 분당 30회 요청 제한 (무료)
  • 인증: 불필요 (Public API)
  • 한국 접근: ✅ 차단 없음

업비트 API

  • 기본 URL: https://api.upbit.com/v1
  • 엔드포인트: /ticker - 원화 기준 코인 가격 조회
  • Rate Limit: 초당 10회 요청 제한
  • 인증: 불필요 (Public API)

환율 API

공포&탐욕 지수 API

응답 시간

  • CoinGecko API: 10초 이내 타임아웃
  • 업비트 API: 5초 이내 타임아웃
  • 환율 API: 5초 이내 타임아웃
  • 공포&탐욕 지수 API: 5초 이내 타임아웃

📁 프로젝트 구조

crypto-market-mcp/
├── main.py              # 메인 서버 파일
├── requirements.txt     # Python 의존성
├── .gitignore          # Git 무시 파일
└── README.md           # 프로젝트 문서

⚠️ 주의사항

  1. 환율: 김치 프리미엄은 실시간 환율을 사용하며, 환율 조회 실패시 기능이 중단됩니다.
  2. 심볼 형식: 바이낸스는 USDT 기준, 업비트는 KRW 기준으로 조회됩니다.
  3. 지원 코인: 김치 프리미엄은 업비트와 바이낸스에서 모두 거래되는 코인만 지원합니다.
  4. API 제한: 각 API의 rate limit을 준수합니다.
  5. 에러 처리: 환율 조회 실패시 명확한 에러 메시지와 재시도 제안을 제공합니다.

🐛 에러 처리

  • 입력 오류: 잘못된 심볼 형식, 지원하지 않는 코인
  • API 오류: 바이낸스/업비트 API 연결 실패
  • 환율 오류: 환율 조회 실패시 김치 프리미엄 계산 중단
  • 시스템 오류: 예상치 못한 오류

모든 에러는 구조화된 형태로 반환되며, 타임스탬프와 재시도 제안이 포함됩니다.

📞 지원

문제가 발생하거나 기능 요청이 있으시면 이슈를 등록해주세요.

개발자: Crypto Market MCP Team
버전: 1.0.0
라이선스: MIT