Upbit MCP 서버

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	Upbitで取引可能な全マーケットコードの一覧	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
}

💬 자연어 요청 예시

• "비트코인 일봉 캔들스틱 차트를 생성해주세요"
• "2024년 6월부터 12월까지 이더리움 차트를 보여주세요"
• "리플 4시간봉 라인 차트를 거래량과 함께 만들어주세요"
• "도지코인 15분봉 차트를 이동평균선 없이 생성해주세요"

기술적 세부사항

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

Docker 환경 설정

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

# 의존성 패키지
matplotlib>=3.7.0
pillow>=10.0.0

# 볼륨 마운트
/app/uploads/charts -> Nginx 정적 파일 서빙

차트 기능의 장점

1. 즉시 시각화: 복잡한 데이터를 한눈에 파악 가능한 차트로 변환
2. 웹 접근성: 생성된 이미지를 바로 웹에서 확인 가능
3. 유연한 설정: 다양한 차트 타입과 시간 간격 지원
4. 날짜 범위: 특정 기간의 과거 데이터 차트 생성 가능
5. 기술적 분석: 이동평균선과 거래량으로 추가 인사이트 제공

수행 가능한 기능 목록 (세부)

시장 데이터 조회

• 특정 암호화폐의 현재 시세(가격, 변동률 등) 조회 (get_ticker)
• 특정 마켓의 실시간 매수/매도 호가 정보 조회 (get_orderbook)
• 특정 마켓의 가장 최근 단일 체결 내역 조회 (get_trades)
• (get_market_summary는 현재 get_ticker와 유사 기능 제공 가능성)
• 지정된 마켓의 캔들(시고저종) 데이터 조회 (get_candles)
• 지정된 마켓과 인터벌에 대한 다양한 기술적 지표 및 분석 신호 확인 (technical_analysis)
• 시각적 차트 이미지 생성 및 웹 URL 제공 (generate_chart_image)
• 업비트 거래 가능 전체 마켓 코드 목록 확인 (get_markets, market://list 리소스)

계정 정보 조회

• 전체 계좌 잔고 및 보유 자산 정보 확인 (get_accounts)
• 미체결 주문 목록 조회 (get_orders)
• 특정 주문의 상세 내역 조회 (get_order)
• 입출금 내역 조회 (get_deposits_withdrawals)

거래 기능

• 지정가 또는 시장가 매수/매도 주문 생성 (create_order)
• 특정 주문 취소 (cancel_order)
• 디지털 자산 또는 원화 출금 요청 (create_withdraw)

LLM 에이전트 보조

• 시세 정보 사용자 설명 생성 (explain_ticker 프롬프트)
• 포트폴리오 분석 요청 생성 (analyze_portfolio 프롬프트)
• 주문 방법 안내 (order_help 프롬프트)
• 트레이딩 전략 수립 가이드 (trading_strategy 프롬프트)

백테스팅 및 전략 분석

• 다양한 거래 전략의 과거 성과 시뮬레이션 (backtesting)
• SMA 교차, RSI 과매도/과매수, 볼린저 밴드, MACD 신호선 전략 지원
• 상세한 성과 지표 및 위험 분석 (수익률, 샤프 지수, 최대 낙폭 등)
• 자연어 백테스팅 요청 처리 (backtesting_guide 프롬프트)

차트 이미지 생성

• 캔들스틱, 라인, OHLC 차트 생성 (generate_chart_image)
• 날짜 범위 지정 가능 (과거 특정 기간 차트 생성)
• 거래량 및 이동평균선 포함/제외 선택
• 웹 접근 가능한 이미지 URL 자동 생성
• 다양한 시간 간격 지원 (1분봉~월봉)

채팅 예시 (원본 프로젝트 기준)

아래는 원본 프로젝트([solangii/upbit-mcp-server](https://github.com/solangii/upbit-mcp-server))의 채팅 예시 이미지입니다. 이 프로젝트는 해당 기능을 기반으로 n8n 연동 및 기능 개선이 이루어졌습니다.

프로젝트 구조

프로젝트의 주요 디렉토리 및 파일은 다음과 같습니다:

• main.py: FastMCP 서버의 메인 실행 파일입니다. 모든 툴, 프롬프트, 리소스를 초기화하고 서버를 실행합니다.
• config.py: Upbit API 키, 기본 API URL 등의 설정을 관리합니다. (실제 키는 .env 파일에 저장)
• docker-compose.yml: Docker를 사용하여 서버를 빌드하고 실행하기 위한 설정 파일입니다. n8n과의 네트워크 연동 설정 등이 포함됩니다.
• requirements.txt / pyproject.toml / uv.lock: Python 프로젝트의 의존성 패키지들을 관리합니다. (uv 사용 권장)
• .env: Upbit API 키와 같이 민감한 환경 변수를 저장하는 파일입니다. (버전 관리에서 제외됨)
• tools/: 업비트 API 기능을 수행하는 개별 MCP 툴 파이썬 파일들이 위치합니다. (예: get_ticker.py, create_order.py)
• prompts/: LLM 에이전트의 행동을 가이드하거나 특정 작업 템플릿을 제공하는 프롬프트 파이썬 파일들이 위치합니다. (예: order_help.py)
• resources/: MCP 서버가 제공하는 리소스(예: 거래 가능 마켓 목록)를 정의하는 파이썬 파일들이 위치합니다. (예: get_market_list.py)
• README.md: 본 프로젝트 설명 파일입니다.

사전 준비 사항

시작하기 전에 Upbit API 키를 발급받아야 합니다:

1. Upbit에 계정이 없다면 먼저 회원가입을 진행합니다.
2. Upbit 개발자 센터로 이동합니다.
3. 새로운 API 키를 생성합니다.
4. API 키에 필요한 권한(조회, 주문, 출금 등)을 적절히 설정합니다.
5. 발급받은 API 키(UPBIT_ACCESS_KEY, UPBIT_SECRET_KEY)를 프로젝트 루트 디렉토리에 .env 파일로 저장합니다 (설치 섹션 참조).

설치 방법

1. 저장소 복제:

   git clone <현재_프로젝트_저장소_URL> # 이 부분은 실제 저장소 URL로 변경해주세요.
   cd upbit-mcp-server
   

2. 의존성 패키지 설치 (uv 권장): uv를 사용하여 Python 프로젝트에 필요한 패키지들을 설치하는 것을 강력히 권장합니다. uv는 기존 pip 및 venv보다 빠르고 효율적인 패키지 관리를 제공합니다.

   주요 의존성 패키지:

   • fastmcp>=0.1.8 (하지만 requirements.txt에서는 1.0.0 사용)
   • httpx>=0.27.0 (HTTP 클라이언트)
   • pyjwt (JWT 토큰 생성)
   • python-dotenv (환경변수 관리)
   • numpy (기술적 분석)
   • pyupbit (업비트 API 지원)
   • uvicorn (ASGI 서버)
   • matplotlib>=3.7.0 (차트 생성)
   • pillow>=10.0.0 (이미지 처리)

   만약 uv가 설치되어 있지 않다면, 다음 방법으로 먼저 설치해주세요:

   # uv 설치 (Linux, macOS, Windows WSL)
   curl -Ls https://astral.sh/uv/install.sh | sh
   
   # Windows (Powershell):
   # irm https://astral.sh/uv/install.ps1 | iex
   
   # 설치 후, 터미널 환경에 맞게 PATH 설정을 업데이트해야 할 수 있습니다.
   # (예: 쉘 설정 파일(~/.bashrc, ~/.zshrc 등)에 export PATH="$HOME/.astral/bin:$PATH" 추가 후 source ~/.bashrc 또는 터미널 재시작)
   # Windows의 경우, 설치 스크립트가 PATH를 자동으로 업데이트하려고 시도할 수 있습니다.
   

   uv 설치 후, 프로젝트 루트 디렉토리에서 다음 명령을 실행하여 uv.lock 파일에 명시된 정확한 버전의 의존성을 설치합니다:

   uv sync
   

   이 명령은 가상 환경을 자동으로 감지하거나 생성하며( .venv 폴더), 필요한 패키지를 설치합니다.

   (대안: 기존 pip 사용 시 - 권장하지 않음)

   # python3 -m venv .venv  # 가상환경 생성 (필요시)
   # source .venv/bin/activate # 가상환경 활성화 (Linux/macOS)
   # .venv\\Scripts\\activate # 가상환경 활성화 (Windows)
   # pip install -r requirements.txt
   

3. 환경 변수 설정: 프로젝트 루트 디렉토리에 .env 파일을 생성하고, 발급받은 Upbit API 키를 다음과 같이 입력합니다:

   UPBIT_ACCESS_KEY=여기에_발급받은_ACCESS_KEY를_입력하세요
   UPBIT_SECRET_KEY=여기에_발급받은_SECRET_KEY를_입력하세요
   

사용 방법

이 서버는 n8n과의 원활한 연동을 위해 Docker Compose를 사용하여 실행하는 것을 권장합니다.

Docker Compose를 이용한 실행 (n8n 연동 권장)

1. docker-compose.yml 설정 확인: 프로젝트에 포함된 docker-compose.yml 파일은 Upbit MCP 서버를 빌드하고 실행하도록 구성되어 있습니다. 주요 설정은 다음과 같습니다:

   • ports: 서버의 포트(예: 8001:8001)를 호스트 머신에 노출시킵니다. 이는 n8n이 (호스트나 다른 Docker 네트워크에서 실행 중일 경우) 서버에 접속할 수 있게 합니다.
   • networks: 서버를 특정 Docker 네트워크(예: nginx-n8n-net)에 연결합니다. n8n과 이 서버가 모두 동일한 Docker 네트워크 상에서 컨테이너로 실행될 때 서로 통신하기 위해 매우 중요합니다. 사용 중인 n8n 컨테이너가 연결된 Docker 네트워크 이름과 동일하게 설정하거나, 필요한 경우 docker-compose.yml 파일 내의 networks 섹션을 직접 수정하십시오. (예: nginx-n8n-net -> 사용자의 n8n 네트워크 이름)
   • env_file: .env 파일로부터 환경 변수를 로드합니다.
   • volumes: 현재 디렉토리를 컨테이너 내부에 마운트하여, 이미지 재빌드 없이 코드 변경사항을 반영할 수 있게 합니다 (개발 시 유용).

2. 서버 시작:

   docker-compose up -d --build
   

   --build 옵션은 Docker 이미지를 강제로 다시 빌드합니다. 코드 변경사항이 있을 때 유용합니다. 서버를 중지하려면 다음 명령을 사용합니다:

   docker-compose down
   

3. 로그 확인: 서버 로그는 다음 명령으로 확인할 수 있습니다:

   docker-compose logs -f upbit-mcp-server
   

n8n 連携

上記の説明どおりに Upbit MCP サーバーが Docker Compose 経由で起動し、n8n インスタンスと同じ Docker ネットワークに接続されている場合は、次のように n8n ワークフローを設定します。

1. n8n ワークフローで HTTP Request ノード、または MCP 関連のコミュニティノード（利用可能な場合）を使用します。
2. SSE エンドポイント URLを http://upbit_mcp_server:8001/sse に設定します。
   • upbit_mcp_server：docker-compose.yml で定義されたサービス名です。Docker 内部の DNS がこの名前を、共有ネットワーク内の適切なコンテナ IP に解決します。
   • 8001：コンテナ内部でサーバーがリッスンするポートです。（ホストポートと同じポートにマッピングされている場合）
   • /sse：FastMCP ライブラリが SSE ストリームに使用する一般的なパスです。ルートパス（/）へのリクエストで 404 Not Found エラーが発生する場合は、/sse パスを試してください。
   • n8n が Docker の外部（例：ローカルマシン）で実行され、MCP サーバーのみが Docker で実行されている場合、URL は http://localhost:8001/sse（または Docker ホストの IP と公開ポート）になります。

⚠️ 注意事項：現在、FastMCP のインポートエラーにより、サーバーが正常に起動しない可能性があります。この問題は優先的に解決する必要があります。

開発サーバーの起動（Docker を使用しない直接テスト用）

開発または直接テストする場合は、Docker を使わずにサーバーを実行できます。

# uv를 사용하여 가상환경 활성화 및 실행 (권장)
uv run python main.py

または、FastMCP の開発モードを使用できます（主に FastMCP < 1.0.0 で使用されていた方法です。現在のバージョンでは uv run または直接実行を推奨します）。

# fastmcp dev main.py # 이 방식은 FastMCP 버전에 따라 다를 수 있습니다.

注意：この方法で直接実行する場合、n8n インスタンスがサーバーの実行ホストとポートにアクセスできる必要があります。n8n と連携する場合は、一般的に Docker を使用するほうが便利で安定しています。

LLM エージェント連携ガイド

この MCP サーバーは、LLM（大規模言語モデル）ベースのエージェントと効果的に連携できるように設計されています。エージェントがこのサーバーの機能を最大限に活用するためのガイドラインをいくつか紹介します。

1. ツール（Tool）の使用方法を理解する

• 目的の把握：上記で説明した各ツールの目的、必要なパラメーター、戻り値を LLM が正確に理解する必要があります。これは、システムプロンプトや別途用意したツール使用ガイドを通じて LLM に提供できます。
• パラメーターの抽出：ユーザーの自然言語による質問から、各ツールに必要なパラメーターを正確に抽出する能力が重要です。たとえば、「ビットコインの現在価格を教えて」という質問から、get_ticker ツールの symbol パラメーターの値として「KRW-BTC」を推論する必要があります。
• 適切なツールの選択：ユーザーのリクエストの意図に最も適したツールを選択する必要があります。たとえば、「ビットコインの価格」には get_ticker を、「ビットコインの最近の約定履歴」には get_trades を使用するように使い分けます。
• エラー処理：ツールの実行中にエラーが発生した場合（例：API 通信の失敗、不正なパラメーターなど）、ツールはエラー情報を含む JSON オブジェクト（例：{\"error\": \"エラーメッセージ\"}）を返します。LLM はこのエラーメッセージをユーザーにわかりやすく伝え、必要に応じて追加情報を求めるか、別の対応を提案する必要があります。（従来の UserError 発生方式から変更されています）

2. プロンプト（Prompt）の活用

• 提供されているプロンプト（explain_ticker、analyze_portfolio、order_help、trading_strategy）は、LLM が特定のタスクを実行したり、ユーザーに情報を提供したりする方法を標準化し、品質を高めるのに役立ちます。
• たとえば、get_ticker で相場情報を取得した後、explain_ticker プロンプトを活用すると、ユーザーにとってよりわかりやすい形に情報を加工して伝えることができます。

3. リソース（Resource）の活用

• market://list などのリソースから、取引可能なマーケット一覧などの動的な情報を取得し、ツールの使用時に正確なパラメーターを構成するために活用できます。

開発に関する注意事項

• ロギング：主要な関数の開始、API 呼び出しの試行、応答結果、エラーの発生などの状況を、print(f\"DEBUG_TA: ...\", flush=True) または print(f\"ERROR_TA: ...\", flush=True) の形式でログに記録し、ターミナルでリアルタイムに確認できます。Docker を使用する場合は、docker-compose logs -f upbit-mcp-server コマンドでログを監視してください。
• 非同期処理：API 呼び出しに関連するツール関数（get_ticker、technical_analysis など）は async def として定義されており、内部で httpx.AsyncClient を使用して非同期 HTTP リクエストを処理します。
• EMA の計算：technical_analysis で MACD などの指標を計算する際、以前は EMA を単純平均（SMA）で近似していましたが、現在はより標準的な EMA の計算方式を適用し、精度を高めています。

現在の課題と解決が必要な事項

✅ 最近完了した主な機能

1. チャート画像生成システムの構築完了

   • tools/generate_chart_image.py を実装
   • Matplotlib ベースのローソク足／ライン／OHLC チャート生成
   • 日付範囲の指定機能（過去の特定期間のチャートを生成可能）
   • Nginx + SSL ベースのウェブ配信（charts.resteful3.shop）
   • Docker 環境の完全な構成

2. バックテストシステムの安定化完了

   • 主要な戦略（SMA、RSI、ボリンジャーバンド、MACD）がすべて正常に動作
   • 正確なポートフォリオ追跡と損益計算
   • 自然言語によるリクエスト処理用のプロンプトを完成

3. バックテストのチャート可視化機能が完成

   • tools/generate_backtest_chart.py を実装
   • 3 段構成のチャート（価格＋売買シグナル、ポートフォリオ価値の変化、取引量＋取引時点）
   • バックテスト実行時のチャート自動生成オプション（generate_chart: bool = True）
   • すべての売買シグナルとポートフォリオの変化を正確に可視化

4. バックテストシステムの主なバグを修正

   • 売却数量の記録に関する問題を解決：すべての戦略で売却時の数量が 0 と記録されていた問題を修正
   • ポートフォリオ概要の欠落に関する問題を解決：RSI、ボリンジャーバンド戦略で portfolio_summary の計算が欠落していた問題を修正
   • enhance_trade_history のエラーを解決：'cash_balance' キーエラーの原因となる関数呼び出しを削除
   • MACD 戦略を全面的に修正：売却ロジック、ポートフォリオ概要、エラー処理をすべて正常化
   • すべてのバックテスト戦略（SMA、RSI、ボリンジャーバンド、MACD、ブレイクアウト）が完全に正常動作することを確認

🚨 緊急の修正が必要

1. FastMCP インポートエラー：main.py の from mcp.server.fastmcp import FastMCP, Context で、モジュールが見つからないエラーが発生
2. 依存関係のバージョン不一致：
   • requirements.txt：fastmcp==1.0.0
   • pyproject.toml：fastmcp>=0.1.8

📋 今後の改善方針（TODO）

機能拡張

• さらに多くのテクニカル指標を追加（例：Stochastic Oscillator、Ichimoku Cloud など）
• リアルタイムの WebSocket データストリーミングに対応（別のツールまたは機能として）
• ユーザーごとの設定を保存する機能（例：好みのテクニカル指標、アラート設定など）
• ツールパラメーターの検証を強化
• さらに多様なプロンプトとリソースを追加
• テストコードのカバレッジを拡大

チャート機能の改善

• さらに多くのチャートタイプを追加（平均足、レンコチャートなど）
• テクニカル指標のオーバーレイを追加（RSI、MACD、ボリンジャーバンドなど）
• インタラクティブなチャートに対応（Plotly など）
• チャートスタイルのカスタマイズオプション
• 複数市場の比較チャート

ライセンス

MIT

---

⚠️ 免責事項（DISCLAIMER）

本プロジェクトは教育および研究目的で提供されています。

🚨 重要な警告

1. 投資損失に対する責任の否認

   • 本ソフトウェアの使用によって発生するすべての投資損失について、開発者、コントリビューター、配布者は一切の責任を負いません。
   • 暗号資産への投資には高いリスクが伴い、投資元本の全額を失う可能性があります。

2. バックテスト結果の限界

   • バックテスト結果は過去のデータに基づくシミュレーションであり、将来の利益を保証するものではありません。
   • 実際の取引環境では、スリッページ、流動性不足、取引所の障害など、バックテストで考慮されていない要素がパフォーマンスに影響する可能性があります。

3. ソフトウェアの品質保証の否認

   • 本ソフトウェアは「現状有姿（AS-IS）」で提供され、明示または黙示を問わず、いかなる保証もありません。
   • ソフトウェアのエラー、バグ、セキュリティ上の脆弱性による損失について、責任を負いません。

4. ユーザーの責任

   • 本プロジェクトを使用する前に、十分なテストと検証を行ってください。
   • 実際の資金を投資する前に、デモ取引や少額でのテストを通じて、システムを十分に理解してください。
   • 投資の決定はすべてユーザー自身の責任で行い、専門家の助言を求めてください。

📋 推奨事項

• 本プロジェクトは教育目的に限って使用してください。
• 実際の投資に使用する前に、十分な検証とテストを行ってください。
• 損失を許容できる範囲内でのみ投資してください。
• 投資する前に、専門家の助言を求めてください。

本プロジェクトを使用することにより、上記の免責事項に同意したものとみなされます。