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 Agent 在特定情境下做出更恰当的回应或执行任务。

提示词名称	功能说明
explain_ticker	生成用于向用户说明通过 get_ticker 获取的行情数据的文本。
analyze_portfolio	根据通过 get_accounts 获取的账户信息，生成请求分析投资组合的文本。
order_help	提供 create_order 工具的使用方法及订单相关帮助。
trading_strategy	引导制定交易策略，并生成引导使用相关工具的文本。
backtesting_guide	提供将自然语言回测请求转换为工具参数的指南。

提供的资源（Resources）

提供 MCP 客户端或 LLM Agent 可供参考的静态或动态数据。

资源 URI	提供的数据	相关工具/功能
market://list	Upbit 上可交易的所有市场代码列表	get_market_list.py

技术分析工具详情

tools/technical_analysis.py 中提供的 technical_analysis 函数会提供以下技术指标及分析信息。查询蜡烛图数据时，已修改为使用 Upbit API 的准确端点（对于日线/周线/月线，使用 /candles/days、/candles/weeks、/candles/months），并在计算 MACD 时使用指数移动平均线（EMA）而非简单移动平均线（SMA），以提高准确性。

功能分类	详细指标/项目	默认设置/参考	提供的信号
蜡烛图数据	查询指定市场和时间间隔的蜡烛图	使用 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 Agent 集成指南

此 MCP 服务旨在与基于 LLM（大语言模型）的 Agent 高效集成。以下是帮助 Agent 充分利用此服务功能的一些指南。

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 等指标时，最初使用简单移动平均（SMA）近似计算 EMA；目前已采用更标准的 EMA 计算方法，以提高准确性。

当前问题及待解决事项

✅ 最近完成的主要功能

1. 图表图片生成系统已完成构建

   • 实现了 tools/generate_chart_image.py
   • 基于 Matplotlib 生成蜡烛图、折线图和 OHLC 图表
   • 支持指定日期范围（可生成过去特定时间段的图表）
   • 基于 Nginx + SSL 的 Web 服务（charts.resteful3.shop）
   • Docker 环境已完整配置

2. 回测系统已完成稳定化

   • 所有主要策略（SMA、RSI、布林带、MACD）均正常运行
   • 可准确跟踪投资组合并计算盈亏
   • 已完成处理自然语言请求的提示词

3. 回测图表可视化功能已完成

   • 实现了 tools/generate_backtest_chart.py
   • 三部分图表（价格 + 交易信号、投资组合价值变化、交易量 + 交易时点）
   • 回测时提供自动生成图表的选项（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）

功能扩展

• 添加更多技术指标（例如：随机振荡指标、Ichimoku Cloud 等）
• 支持实时 WebSocket 数据流（作为单独的工具或功能）
• 支持保存用户设置（例如：偏好的技术指标、提醒设置等）
• 加强工具参数验证
• 添加更多提示词和资源
• 扩大测试代码覆盖率

图表功能改进

• 添加更多图表类型（Heikin Ashi、Renko 图表等）
• 添加更多技术指标叠加层（RSI、MACD、布林带等）
• 支持交互式图表（例如 Plotly）
• 提供图表样式自定义选项
• 支持多市场对比图表

许可证

MIT

---

⚠️ 免责声明（DISCLAIMER）

本项目仅用于教育和研究目的。

🚨 重要警告

1. 不对投资损失承担责任

   • 对于使用本软件造成的任何投资损失，开发者、贡献者和发布者概不负责。
   • 加密货币投资风险较高，可能损失全部投资本金。

2. 回测结果的局限性

   • 回测结果是基于历史数据的模拟，不保证未来收益。
   • 在实际交易环境中，滑点、流动性不足、交易所故障等回测未考虑的因素都可能影响表现。

3. 不提供软件质量保证

   • 本软件按“现状”（AS-IS）提供，不附带任何明示或默示保证。
   • 对于由软件错误、缺陷或安全漏洞造成的损失，概不负责。

4. 用户责任

   • 使用本项目之前，请进行充分的测试和验证。
   • 投入实际资金之前，请通过模拟交易或小额测试，充分了解系统。
   • 投资决策完全由用户负责，请寻求专业建议。

📋 建议

• 本项目仅应用于教育目的。
• 用于实际投资之前，请进行充分的验证和测试。
• 投资金额请控制在可承受范围内。
• 投资前请寻求专业建议。

使用本项目即视为同意上述免责声明。