Upbit MCP 서버

이 프로젝트는 Upbit 암호화폐 거래소 OpenAPI를 위한 MCP(Model Context Protocol) 서버 구현입니다. Upbit 거래소의 다양한 서비스(시세, 호가창, 체결 내역, 차트 데이터 조회, 계정 정보 확인, 주문 생성 및 취소, 입출금 관리, 기술적 분석 등)와 상호작용할 수 있는 도구들을 제공합니다.

본 프로젝트는 solangii/upbit-mcp-server를 기반으로 합니다.
원본 프로젝트는 MCP stdio 통신 방식으로 설계되어 n8n과 같은 워크플로우 자동화 도구와의 직접적인 연동에 어려움이 있었습니다. 이 버전은 n8n과의 원활한 연동을 위해 SSE(Server-Sent Events)를 지원하도록 핵심 로직이 수정되었으며, Docker 및 Docker Compose를 활용한 배포 방식을 기본으로 제공합니다. 또한, FastMCP 1.0.0 버전에 맞게 내부 로직 및 에러 처리 방식이 개선되었고, 기술적 분석 도구의 정확성과 안정성이 향상되었습니다.

주요 기능

- 실시간 시장 데이터 조회 (현재가, 호가창, 최근 체결 내역, 캔들 데이터 등)
- 계정 정보 확인 (전체 잔고, 미체결 주문, 개별 주문 상세, 입출금 내역 등)
- 주문 실행 및 취소 (지정가/시장가 주문, 주문 취소)
- 기술적 분석 지표 및 신호 제공 (EMA 기반 MACD 계산, API 엔드포인트 수정 등 정확도 향상)
- 백테스팅 시스템 (SMA, RSI, 볼린저 밴드, MACD 전략 지원, 자연어 요청 처리 가능)
- 차트 이미지 생성 기능 (캔들스틱, 라인, OHLC 차트 지원, 날짜 범위 지정 가능, 웹 접근 가능한 이미지 URL 제공)
- LLM 에이전트의 답변 및 행동을 가이드하기 위한 프롬프트 및 리소스 제공
- FastMCP 1.0.0 기반의 SSE(Server-Sent Events) 통신 지원으로 n8n 등 외부 시스템과의 유연한 연동
- 주요 기능에 대한 상세 로깅 추가로 디버깅 편의성 증대
- FastMCP 1.0.0 표준에 맞춘 에러 처리 (툴 실행 오류 시, 에러 메시지를 포함한 JSON 객체 반환)

제공 툴 (Tools)

본 MCP 서버는 다음과 같은 툴들을 제공하여 LLM 에이전트가 업비트 API와 상호작용할 수 있도록 합니다.

| 툴 이름 | 기능 설명 | 주요 파라미터 (예시) |
| ---------------------------- | ------------------------------------------------------------------------- | ------------------------ |
| get_ticker | 특정 암호화폐 마켓의 현재 시세 정보(가격, 변동률 등)를 조회합니다. | symbol="KRW-BTC" |
| get_orderbook | 특정 마켓의 실시간 매수/매도 호가 정보를 조회합니다. | symbol="KRW-BTC" |
| get_trades | 특정 마켓의 가장 최근 단일 체결 내역을 조회합니다. (API 기본값) | symbol="KRW-BTC" |
| get_accounts | 사용자의 전체 계좌 잔고 및 보유 자산 정보를 조회합니다. | - |
| create_order | 지정가 또는 시장가로 매수/매도 주문을 생성합니다. | market, side, ord_type, volume, price |
| get_orders | 사용자의 미체결 주문 목록을 조회합니다. | market (선택) |
| get_order | 특정 주문의 상세 내역을 조회합니다. | uuid |
| cancel_order | 특정 주문을 취소합니다. | uuid |
| get_market_summary | KRW 전체 마켓의 현재 상황을 동적으로 요약하여 제공합니다. | major_n, top_n, sort_by |
| get_deposits_withdrawals | 사용자의 입출금 내역을 조회합니다. | currency (선택) |
| get_markets | 업비트에서 거래 가능한 전체 마켓 코드 목록을 조회합니다. | - |
| get_candles | 지정된 마켓의 캔들(시고저종) 데이터를 조회합니다. | market, interval, count |
| create_withdraw | 디지털 자산 또는 원화 출금을 요청합니다. | currency, amount, address |
| technical_analysis | 지정된 마켓과 인터벌에 대한 다양한 기술적 지표 및 분석 신호를 제공합니다. (API 엔드포인트 수정 및 MACD 계산 로직 개선) | market, interval |
| backtesting | 지정된 전략으로 과거 데이터를 이용한 백테스팅을 수행하고 성과 지표를 제공합니다. (SMA, RSI, 볼린저 밴드, MACD 전략 지원) | market, strategy_type, start_date, end_date, strategy_params |
| generate_chart_image | 지정된 마켓의 차트 이미지를 생성하고 웹 접근 가능한 URL을 제공합니다. (캔들스틱, 라인, OHLC 차트, 날짜 범위 지정 가능) | market, interval, chart_type, start_date, end_date |

제공 프롬프트 (Prompts)

LLM 에이전트가 특정 상황에 더 적절하게 응답하거나 작업을 수행하도록 안내하는 프롬프트 템플릿을 제공합니다.

| 프롬프트 이름 | 기능 설명 |
| ---------------------- | ---------------------------------------------------------------------- |
| explain_ticker | get_ticker로 얻은 시세 데이터를 사용자에게 설명하기 위한 텍스트를 생성합니다. |
| analyze_portfolio | get_accounts로 얻은 계좌 정보를 바탕으로 포트폴리오 분석을 요청하는 텍스트를 생성합니다. |
| order_help | create_order 툴 사용법 및 주문 관련 도움말을 제공합니다. |
| trading_strategy | 트레이딩 전략 수립 과정을 안내하고 관련 툴 사용을 유도하는 텍스트를 생성합니다. |
| backtesting_guide | 자연어 백테스팅 요청을 툴 파라미터로 변환하는 가이드를 제공합니다. |

제공 리소스 (Resources)

MCP 클라이언트나 LLM 에이전트가 참조할 수 있는 정적 또는 동적 데이터를 제공합니다.

| 리소스 URI | 제공 데이터 | 관련 툴/기능 |
| ----------------- | ----------------------------------------- | ---------------------- |
| market://list | 업비트에서 거래 가능한 전체 마켓 코드 목록 | get_market_list.py |

기술적 분석 도구 상세

tools/technical_analysis.py 에서 제공하는 technical_analysis 함수는 다음의 기술적 지표 및 분석 정보를 제공합니다. 캔들 데이터 조회 시 Upbit API의 정확한 엔드포인트(일/주/월봉의 경우 /candles/days, /candles/weeks, /candles/months 사용)를 사용하도록 수정되었으며, MACD 계산 시 단순 이동 평균(SMA) 대신 지수 이동 평균(EMA)을 사용하여 정확도를 높였습니다.

| 기능 분류 | 세부 지표/항목 | 기본 설정/참고 | 제공 신호 |
|---|---|---|---|
| 캔들 데이터 | 지정된 마켓 및 인터벌의 캔들 조회 | Upbit API 사용 (기본 200개, 정확한 엔드포인트 사용) | - |
| 이동 평균선 (SMA) | 20, 50, 200일(충분한 데이터 시) 단순 이동 평균 | | "bullish", "bearish", "neutral" |
| 상대강도지수 (RSI) | 14일 RSI | | "overbought", "oversold", "neutral" |
| 볼린저 밴드 | 20일 기준 중간, 상단, 하단 밴드 | | "overbought", "oversold", "neutral" |
| MACD | MACD 선 (12, 26일 EMA), 신호선 (9일 EMA), 히스토그램 | EMA 기반 계산 | "bullish", "bearish", "neutral" |
| 거래량 분석 | 현재 거래량, 20일 평균 거래량, 비율 | | "high", "low", "neutral" |
| 종합 신호 | 투자 판단 보조 신호 | 여러 지표 신호 종합 (MA, RSI, BB, MACD 기반) | "strong_buy", "buy", "strong_sell", "sell", "neutral" |

참고: technical_analysis 함수는 market (예: "KRW-BTC") 및 interval (예: "day", "minute60")을 인자로 받습니다. 제공되는 신호는 투자 결정에 대한 참고 자료이며, 실제 투자는 사용자의 신중한 판단 하에 이루어져야 합니다. 데이터 부족 시 지표 값은 "N/A"로 표시될 수 있습니다.

백테스팅 도구 상세

tools/backtesting.py에서 제공하는 backtesting 함수는 다양한 거래 전략을 과거 데이터에 적용하여 성과를 시뮬레이션하고 분석합니다. 2025년 1월 기준으로 완전히 구현되어 모든 주요 기능이 정상 작동합니다.

지원하는 백테스팅 전략

| 전략 타입 | 전략명 | 설명 | 주요 파라미터 |
|---|---|---|---|
| sma_crossover | SMA 교차 전략 | 단기/장기 이동평균선의 골든크로스/데드크로스 기반 매매 | fast_period, slow_period |
| rsi_oversold | RSI 과매도/과매수 전략 | RSI 지표의 과매도/과매수 구간 진입 시 매매 | rsi_period, oversold_threshold, overbought_threshold |
| bollinger_bands | 볼린저 밴드 전략 | 볼린저 밴드 내 상대적 위치 기반 매매 | period, std_dev, buy_threshold, sell_threshold |
| macd_signal | MACD 신호선 전략 | MACD선과 신호선의 교차 기반 매매 | fast_period, slow_period, signal_period |

지원하는 시간 간격

- 분봉: 1분(minute1), 3분(minute3), 5분(minute5), 10분(minute10), 15분(minute15), 30분(minute30)
- 시간봉: 1시간(minute60), 4시간(minute240)
- 일봉: day
- 주봉: week
- 월봉: month

제공하는 성과 지표

백테스팅 결과로 다음과 같은 상세한 성과 지표를 제공합니다:

| 지표 분류 | 세부 지표 | 설명 |
|---|---|---|
| 포트폴리오 요약 | initial_capital | 초기 자본금 |
| | final_cash_balance | 최종 현금 잔고 |
| | final_asset_quantity | 최종 자산 보유량 |
| | final_asset_price | 최종 자산 가격 |
| | final_asset_value | 최종 자산 평가가치 |
| | final_total_value | 최종 총 포트폴리오 가치 |
| | absolute_profit | 절대 수익 금액 |
| | position_status | 포지션 상태 (CASH/HOLDING_ASSET/MIXED) |
| 수익률 지표 | total_return | 백테스트 기간 총 수익률 |
| | annualized_return | 연환산 수익률 |
| | realized_return | 실현 수익률 |
| | unrealized_return | 미실현 수익률 |
| 손익 분석 | realized_profit | 실현 손익 (완료된 거래의 손익) |
| | unrealized_profit | 미실현 손익 (보유 포지션의 손익) |
| 위험 지표 | volatility | 연율화 변동성 |
| | sharpe_ratio | 샤프 지수 (위험 대비 수익률) |
| | max_drawdown | 최대 낙폭 |
| 거래 성과 | win_rate | 승률 (수익 거래 비율) |
| | profit_factor | 프로핏 팩터 (총 이익/총 손실) |
| | total_trades | 총 거래 횟수 |
| 상세 분석 | monthly_returns | 월별 수익률 상세 |
| | drawdown_periods | 주요 드로우다운 구간 분석 |
| | trade_history | 모든 거래 내역 상세 (개별 거래 손익 포함) |

자연어 백테스팅 사용 예시

backtesting_guide 프롬프트를 통해 자연어로 백테스팅을 요청할 수 있습니다:

📝 사용자 요청 예시

"비트코인 20일선과 50일선 골든크로스 전략으로 2024년 전체 기간 일봉 백테스팅해줘"
"이더리움 RSI 14일 과매도 25, 과매수 75 전략, 2024년 하반기 4시간봉으로 분석해줘"
"리플 볼린저밴드 20일 2시그마 전략으로 2024년 상반기 백테스팅 결과 보여줘"
"도지코인 MACD 12-26-9 신호선 교차 전략으로 2024년 6월~12월 백테스팅 분석해줘"

🤖 LLM 에이전트 응답 예시 (프롬프트 활용)

사용자: "비트코인 20일선과 50일선 골든크로스 전략으로 2024년 전체 기간 일봉 백테스팅해줘"

LLM: 비트코인 SMA 교차 전략 백테스팅을 진행하겠습니다. 다음 파라미터로 분석하겠습니다:
- 마켓: KRW-BTC
- 전략: SMA 교차 (20일선과 50일선)
- 기간: 2024년 1월 1일 ~ 2024년 12월 31일
- 시간간격: 일봉(day)

{
  "market": "KRW-BTC",
  "strategy_type": "sma_crossover",
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "interval": "day",
  "strategy_params": {
    "fast_period": 20,
    "slow_period": 50
  }
}

사용자: "리플 볼린저밴드 전략으로 최근 3개월 4시간봉 백테스팅해줘"

LLM: 리플(XRP) 볼린저 밴드 전략 백테스팅을 실행하겠습니다:
- 마켓: KRW-XRP
- 전략: 볼린저 밴드 (기본 20일, 2시그마)
- 기간: 최근 3개월
- 시간간격: 4시간봉

{
  "market": "KRW-XRP",
  "strategy_type": "bollinger_bands",
  "start_date": "2024-10-01",
  "end_date": "2024-12-31",
  "interval": "minute240",
  "strategy_params": {
    "period": 20,
    "std_dev": 2.0,
    "buy_threshold": 0.2,
    "sell_threshold": 0.8
  }
}

💡 프롬프트 변환 가이드

backtesting_guide 프롬프트는 다음과 같은 자연어 표현을 툴 파라미터로 변환합니다:

| 자연어 표현 | 툴 파라미터 변환 |
|---|---|
| "20일선과 50일선 골든크로스" | strategy_type: "sma_crossover", fast_period: 20, slow_period: 50 |
| "RSI 과매도 25, 과매수 75" | strategy_type: "rsi_oversold", oversold_threshold: 25, overbought_threshold: 75 |
| "볼린저밴드 20일 2시그마" | strategy_type: "bollinger_bands", period: 20, std_dev: 2.0 |
| "MACD 12-26-9" | strategy_type: "macd_signal", fast_period: 12, slow_period: 26, signal_period: 9 |
| "2024년 상반기" | start_date: "2024-01-01", end_date: "2024-06-30" |
| "최근 3개월" | 현재 날짜 기준 3개월 전부터 |
| "4시간봉" | interval: "minute240" |
| "일봉" | interval: "day" |

백테스팅 시스템 특징

- 정확한 API 연동: Upbit API의 모든 시간 간격에 대해 올바른 엔드포인트 사용
- 페이징 처리: 200개 제한을 넘는 긴 기간 데이터도 자동으로 수집
- 안정적인 계산: 무한 루프 및 API 오류 문제 해결 완료
- 상세한 분석: 단순 수익률뿐만 아니라 리스크 조정 지표까지 제공
- 유연한 파라미터: 각 전략별로 세부 파라미터 조정 가능
- 🆕 완전한 포트폴리오 추적: 최종 잔고, 포지션 상태, 실현/미실현 손익 명확 표시
- 🆕 개별 거래 분석: 각 거래의 손익률과 포트폴리오 영향 상세 제공

개선된 백테스팅 결과 예시

{
  "portfolio_summary": {
    "initial_capital": 1000000,
    "final_cash_balance": 0,
    "final_asset_quantity": 0.00899,
    "final_asset_price": 139300000,
    "final_asset_value": 1252507,
    "final_total_value": 1252507,
    "absolute_profit": 252507,
    "position_status": "HOLDING_ASSET",
    "realized_profit": -218101,
    "unrealized_profit": 470608,
    "realized_return": -0.218,
    "unrealized_return": 0.471
  },
  "performance_metrics": {
    "total_return": 0.2525,
    "annualized_return": 0.2971,
    "volatility": 0.2554,
    "sharpe_ratio": 1.16,
    "max_drawdown": -0.2928,
    "win_rate": 0.0,
    "profit_factor": 0,
    "total_trades": 5
  },
  "trade_history": [
    {
      "date": "2024-05-30",
      "action": "BUY",
      "price": 94593000,
      "quantity": 0.01053,
      "commission": 500,
      "portfolio_value": 995500,
      "trade_profit": 0,
      "trade_return": 0
    },
    {
      "date": "2024-06-26", 
      "action": "SELL",
      "price": 86027000,
      "quantity": 0.01053,
      "commission": 453,
      "portfolio_value": 905185,
      "trade_profit": -90315,
      "trade_return": -0.096
    }
  ]
}

이제 "초기 자본 1,000,000원으로 시작해서 최종적으로 1,252,507원이 되었다"는 것을 명확히 알 수 있습니다!

⚠️ 면책 조항: 백테스팅 결과는 과거 데이터를 기반으로 한 시뮬레이션이며, 미래 수익을 보장하지 않습니다. 실제 투자 결정은 신중한 판단 하에 이루어져야 합니다.

차트 이미지 생성 도구 상세

tools/generate_chart_image.py에서 제공하는 generate_chart_image 함수는 지정된 마켓의 시각적 차트를 생성하고 웹에서 접근 가능한 이미지 URL을 제공합니다. 2025년 1월 기준으로 완전히 구현되어 모든 주요 기능이 정상 작동합니다.

지원하는 차트 기능

| 기능 분류 | 세부 옵션 | 설명 | 기본값 |
|---|---|---|---|
| 차트 타입 | candlestick | 캔들스틱 차트 (시가, 고가, 저가, 종가 표시) | ✅ 기본값 |
| | line | 라인 차트 (종가만 표시) | |
| | ohlc | OHLC 바 차트 (시고저종 표시) | |
| 시간 간격 | minute1 ~ minute240 | 1분봉부터 4시간봉까지 | day |
| | day, week, month | 일봉, 주봉, 월봉 | |
| 데이터 개수 | count | 표시할 캔들 개수 (10~200개) | 100개 |
| 날짜 범위 | start_date | 시작 날짜 (YYYY-MM-DD 형식) | 없음 (최신 데이터) |
| | end_date | 종료 날짜 (YYYY-MM-DD 형식) | 없음 (최신 데이터) |
| 추가 지표 | include_volume | 거래량 차트 포함 여부 | ✅ 포함 |
| | include_ma | 이동평균선(MA20, MA50) 포함 여부 | ✅ 포함 |

차트 생성 플로우

1. 데이터 수집: Upbit API에서 지정된 마켓과 시간 간격의 캔들 데이터 조회
2. 날짜 필터링: start_date와 end_date가 지정된 경우 해당 범위의 데이터만 추출
3. 차트 생성: Matplotlib을 사용하여 시각적 차트 이미지 생성
- 캔들스틱/라인/OHLC 차트
- 거래량 서브차트 (선택 시)
- 이동평균선 오버레이 (선택 시)
4. 파일 저장: /app/uploads/charts/ 디렉토리에 PNG 파일로 저장
5. URL 반환: https://charts.resteful3.shop/파일명.png 형태의 웹 접근 가능한 URL 제공

차트 이미지 접근

생성된 차트는 별도 서브도메인을 통해 웹에서 바로 접근할 수 있습니다:

- 도메인: charts.resteful3.shop
- SSL 인증서: Let's Encrypt 자동 갱신
- CORS 설정: 모든 도메인에서 접근 가능
- 캐시 설정: 1시간 캐시로 성능 최적화

사용 예시

📝 기본 차트 생성

{
  "market": "KRW-BTC",
  "interval": "day",
  "chart_type": "candlestick",
  "count": 100
}

📅 날짜 범위 지정 차트

{
  "market": "KRW-BTC", 
  "interval": "day",
  "chart_type": "candlestick",
  "start_date": "2024-06-01",
  "end_date": "2024-12-31",
  "count": 200
}

💬 자연어 요청 예시

기술적 세부사항

- 이미지 형식: PNG (고해상도 150 DPI)
- 차트 크기: 12x8 또는 12x10 (거래량 포함 시)
- 한글 폰트: 시스템 기본 폰트 사용
- 색상 구성:
- 상승 캔들: 빨간색
- 하락 캔들: 파란색
- MA20: 주황색
- MA50: 빨간색
- 파일명 형식: {마켓}_{간격}_{타입}_{타임스탬프}.png

Docker 환경 설정

차트 생성을 위한 Docker 환경이 구성되어 있습니다:

```dockerfile