trading-mcp

uv + pydantic + akshare + TA-Lib 기반으로 구축된 거래 데이터 및 기술 지표 MCP 서비스입니다.

프로젝트 내용

• 주식 시세 데이터 조회 및 기본 기술 지표 계산(K-라인, RSI, MA, MACD) 제공.

• 중장기 기본적 분석 데이터 조회(A주 주요 지표, 미국 주식 3대 재무제표, 미국 주식 주요 지표) 제공.

• A주 및 미국 주식(예: AAPL.US)을 지원하는 통합 시장 데이터 액세스 계층.

• Markdown 또는 JSON 출력을 지원하는 MCP 도구화 인터페이스.

프로젝트 아키텍처

• data/: 시장 데이터 액세스 계층. MarketDataClient 인터페이스 + AkshareMarketDataClient 구현.

• services/: 비즈니스 서비스 계층. 원시 시세를 표준 구조로 변환하고 지표 계산을 구동.

• indicators/: 지표 엔진 캡슐화. TA-Lib 기반 통합 호출.

• models/: 도구 요청 및 응답 모델(Pydantic).

• utils/: MCP 출력 포맷팅(표 Markdown 등).

• mcp_app.py / main.py: MCP 서비스 진입점 및 도구 등록.

디렉토리 구조

• config/: 설정 정의(Pydantic Settings).

• data/: 시장 데이터 클라이언트 구현.

• indicators/: 지표 계산 엔진.

• models/: 요청/응답 모델.

• services/: 비즈니스 서비스 계층.

• tests/: 단위 테스트.

• utils/: 출력 포맷팅 및 보조 도구.

• mcp_app.py: MCP 도구 등록.

• main.py: 서비스 시작 진입점.

설치 및 의존성

1. 의존성 설치:

uv sync --extra dev

2. TA-Lib 시스템 라이브러리 설치:

• macOS: brew install ta-lib

• Debian/Ubuntu: sudo apt-get install libta-lib0 libta-lib0-dev

• Windows: 해당 Python 버전에 맞는 사전 컴파일된 wheel 사용

설정 설명 설정은 TRADING_MCP_ 접두사가 붙은 환경 변수로 덮어쓸 수 있습니다:

export TRADING_MCP_ENVIRONMENT=dev
export TRADING_MCP_DATA_DIR=./data
export TRADING_MCP_DEFAULT_SYMBOL=000001
export TRADING_MCP_HOST=0.0.0.0
export TRADING_MCP_PORT=8000
export TRADING_MCP_AKSHARE_PROXY_ENABLED=true
export TRADING_MCP_AKSHARE_PROXY_AUTH_IP=***
export TRADING_MCP_AKSHARE_PROXY_AUTH_TOKEN=*** TRADING_MCP_AKSHARE_PROXY_RETRY=30

필드 의미:

• TRADING_MCP_ENVIRONMENT: 실행 환경 식별자(예: dev / test / prod).

• TRADING_MCP_DATA_DIR: 로컬 데이터 디렉토리.

• TRADING_MCP_DEFAULT_SYMBOL: 기본 시세 대상.

• TRADING_MCP_HOST: MCP 서비스 리스닝 주소.

• TRADING_MCP_PORT: MCP 서비스 포트.

• TRADING_MCP_AKSHARE_PROXY_ENABLED: akshare-proxy-patch 활성화 여부.

• TRADING_MCP_AKSHARE_PROXY_AUTH_IP: akshare-proxy-patch 인증 게이트웨이 IP; 설정되지 않으면 패치가 설치되지 않음.

• TRADING_MCP_AKSHARE_PROXY_AUTH_TOKEN: 선택적 인증 토큰.

• TRADING_MCP_AKSHARE_PROXY_RETRY: 패치 내부 재시도 횟수.

동방재부(East Money) 안티 크롤링 프록시 설명:

• 프로젝트에 akshare-proxy-patch가 내장되어 있으며, data/akshare_client.py를 가져올 때 자동으로 설치를 시도합니다.

• TRADING_MCP_AKSHARE_PROXY_AUTH_IP가 설정되고 TRADING_MCP_AKSHARE_PROXY_ENABLED=true일 때만 활성화됩니다.

• 패치는 동방재부 관련 도메인 요청만 후킹하며, 다른 비대상 사이트에는 영향을 주지 않습니다.

Python 사용법

from trading_mcp.config import Settings
from trading_mcp.data import AkshareMarketDataClient
from trading_mcp.indicators import IndicatorEngine

settings = Settings(environment="dev", data_dir="./data", default_symbol="000001")
client = AkshareMarketDataClient()
frame = client.fetch(settings.default_symbol, "2024-01-01", "2024-02-01")

engine = IndicatorEngine()
close_series = frame["close"] if "close" in frame.columns else frame.iloc[:, 0]
result = engine.compute("sma", close_series, timeperiod=5)
print(result.tail())

MCP 서비스 MCP 서비스 시작(streamable HTTP):

python main.py

MCP Inspector 시작(WSL 적응, 호스트 머신에서 액세스 가능):

./dev.sh

기본적으로 다음 Inspector 설정이 사용됩니다:

• MCP_INSPECTOR_HOST=0.0.0.0

• MCP_INSPECTOR_CLIENT_PORT=6274

• MCP_INSPECTOR_SERVER_PORT=6277

• MCP_INSPECTOR_AUTO_OPEN=false

Windows 호스트 브라우저에서 우선적으로 액세스:

http://localhost:6274

로컬 머신에서 WSL localhost 포워딩이 활성화되지 않은 경우, WSL 내에서 hostname -I를 실행하여 IP를 확인한 후 호스트 머신에서 http://<wsl-ip>:6274로 액세스할 수 있습니다.

로컬 Linux 환경에서만 액세스하려면 다음으로 덮어쓸 수 있습니다:

MCP_INSPECTOR_HOST=127.0.0.1 ./dev.sh

주의: Inspector 프록시는 로컬 프로세스를 시작할 수 있는 기능이 있습니다. 0.0.0.0은 신뢰할 수 있는 네트워크 환경에서만 사용해야 합니다.

사용 가능한 도구:

• trading_kline(symbol, limit=30, offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_macd(symbol, limit=30, fast_period=12, slow_period=26, signal_period=9, offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_rsi(symbol, limit=30, period=14, offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_ma(symbol, limit=30, period=20, ma_type="sma", offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_volume(symbol, limit=30, offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_fund_flow_individual_em(symbol, limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_fund_flow_individual_rank_em(indicator="5일", limit=30, offset=0, response_format="markdown")

• trading_fund_flow_sector_rank_em(indicator="今日", sector_type="行业资金流", sort_by="主力净流入", limit=30, offset=0, response_format="markdown")

• trading_fund_flow_sector_summary_em(symbol, indicator="今日", limit=30, offset=0, response_format="markdown")

• trading_fundamental_cn_indicators(symbol, indicator="按报告期", limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_fundamental_us_report(stock, symbol="资产负债表", indicator="年报", limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_fundamental_us_indicators(symbol, indicator="年报", limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_industry_summary_ths(limit=30, offset=0, response_format="markdown")

• trading_industry_index_ths(symbol, limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_industry_name_em(limit=30, offset=0, response_format="markdown")

• trading_board_change_em(limit=30, offset=0, response_format="markdown")

• trading_industry_spot_em(symbol, limit=30, offset=0, response_format="markdown")

• trading_industry_cons_em(symbol, limit=30, offset=0, response_format="markdown")

• trading_industry_hist_em(symbol, period="日k", adjust="none", limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_industry_hist_min_em(symbol, period="5", limit=30, offset=0, response_format="markdown")

• trading_info_global_em(limit=30, offset=0, response_format="markdown")

trading_fundamental_cn_indicators 매개변수 설명:

• indicator 열거형: 按报告期(보고 기간별), 按单季度(분기별)

• symbol 호환 입력: 000001, 000001.SZ, 600519.SH(자동 완성 또는 접미사 정규화)

• 기본적 분석 결과는 원시 행 형식으로 반환: columns + items

trading_fundamental_us_report 매개변수 설명:

• symbol(재무제표 유형) 열거형: 资产负债表(대차대조표), 综合损益表(손익계산서), 现金流量表(현금흐름표)

• indicator(재무제표 주기) 열거형: 年报(연간 보고서), 单季报(분기 보고서), 累计季报(누적 분기 보고서)

• stock 호환 입력: TSLA, AAPL.US, 105.AAPL, BRK.B(내부적으로 AkShare가 인식할 수 있는 티커로 정규화)

trading_fundamental_us_indicators 매개변수 설명:

• indicator 열거형: 年报, 单季报, 累计季报

• symbol 호환 입력: TSLA, AAPL.US, 105.AAPL, BRK.B

• 기본적 분석 결과는 원시 행 형식으로 반환: columns + items

trading_volume 필드 설명:

• 반환 필드: timestamp, volume, amount, turnover_rate

• 단위 전략: 데이터 소스의 원시 단위를 유지하고 응답 필드를 통해 단위를 반환

  • A주: volume_unit=lot, amount_unit=CNY

  • 미국 주식: volume_unit=share, amount_unit=USD

  • turnover_rate_unit=percent

• 주간/월간 데이터가 일간 데이터에서 집계된 경우 turnover_rate는 null일 수 있음

자금 흐름 도구 설명:

• trading_fund_flow_individual_em: 동방재부 개별 종목 자금 흐름, symbol은 000001, 600519.SH, 830799.BJ 지원

• trading_fund_flow_individual_rank_em: 동방재부 개별 종목 자금 흐름 순위

  • indicator 열거형: 今日(오늘), 3日, 5日, 10日

• trading_fund_flow_sector_rank_em: 동방재부 섹터 자금 흐름 순위

  • indicator 열거형: 今日, 5日, 10日

  • sector_type 열거형: 行业资金流(산업 자금 흐름), 概念资金流(테마 자금 흐름), 地域资金流(지역 자금 흐름)

  • sort_by 열거형: 涨跌幅(등락률), 主力净流入(주력 순유입); 기본적으로 主力净流入 기준 내림차순

• 동방재부 순위 인터페이스를 사용할 수 없는 경우:

  • 개별 종목 순위는 동화순(Tonghuashun) 개별 종목 자금 흐름 순위로 대체됨

  • 산업/테마 섹터 순위는 동화순의 해당 순위로 대체됨

  • 대체 후 반환되는 열은 동방재부 원시 열과 다를 수 있음; 地域资金流는 대체되지 않음

• trading_fund_flow_sector_summary_em: 지정된 섹터의 구성 종목 자금 흐름

  • 기본적으로 동방재부를 사용하며, 실패 시 동화순으로 대체됨

  • symbol은 섹터 이름(예: 电源设备, 风电设备)

  • indicator 열거형: 今日, 5日, 10日

  • 대체 후 반환되는 열은 동방재부 원시 열과 다를 수 있음

• 자금 흐름 결과는 통합적으로 원시 테이블로 반환: columns + items

심볼 설명:

• A주 예시: 000001, 300308.SZ

• 미국 주식 예시: AAPL.US, AAPL, 105.AAPL, BRK.B

산업 섹터 도구 설명:

• trading_industry_summary_ths: 동화순 산업 개요 표, 원시 섹터 요약 필드 반환

• trading_industry_index_ths: 동화순 산업 지수, symbol은 섹터 이름, start_date / end_date 지원

• trading_industry_name_em: 동방재부 산업 섹터 이름 목록

• trading_board_change_em: 동방재부 당일 섹터 변동 상세

• trading_industry_spot_em: 동방재부 산업 섹터 실시간 시세, symbol은 섹터 이름

• trading_industry_cons_em: 동방재부 산업 섹터 구성 종목, symbol은 섹터 이름

• trading_industry_hist_em: 동방재부 산업 섹터 과거 시세

  • period 열거형: 日k(일봉), 周k(주봉), 月k(월봉)

  • adjust 열거형: none, qfq(전방 수정), hfq(후방 수정); none은 수정하지 않음을 의미

• trading_industry_hist_min_em: 동방재부 산업 섹터 분봉 과거 시세

  • period 열거형: 1, 5, 15, 30, 60

• 산업 섹터 결과는 통합적으로 원시 테이블로 반환: columns + items

뉴스 도구 설명:

• trading_info_global_em: 동방재부 글로벌 금융 뉴스

• 뉴스 결과는 통합적으로 원시 테이블로 반환: columns + items

응답 구조(structuredContent)

{
  "stock": "TSLA",
  "symbol": "资产负债表",
  "indicator": "年报",
  "columns": ["REPORT_DATE", "ITEM_NAME", "AMOUNT"],
  "items": [],
  "count": 0,
  "total": 0,
  "limit": 30,
  "offset": 0,
  "has_more": false,
  "next_offset": null,
  "start_date": null,
  "end_date": null
}

MCP 데이터 상호작용 프로세스(아키텍처 및 시퀀스 다이어그램)

아래는 현재 MCP의 주요 데이터 상호작용 아키텍처와 시퀀스 다이어그램을 Mermaid로 그린 것으로, 시스템 내에서 요청이 어떻게 흐르는지 이해하는 데 도움이 됩니다.

아키텍처 개요(Flowchart)

flowchart LR
  Client[Client / User] -->|HTTP/Stream 请求| MCP[MCP Server]
  MCP -->|调用工具接口| API[Tool Dispatcher / Handlers]
  API --> Market[MarketDataClient (Akshare / Providers)]
  Market -->|行情数据| Storage[Local Cache / Data Dir]
  API --> Indicator[IndicatorEngine (TA-Lib)]
  Indicator -->|指标结果| Formatter[Response Formatter (Markdown / JSON)]
  Formatter -->|返回| Client
  Market -.->|必要时| Proxy[akshare-proxy-patch]
  MCP -->|注册 & 管理| Inspector[MCP Inspector]

설명:

• MCP Server: 외부 요청(HTTP/stream)을 수신하고, 요청을 해석하여 내부 도구를 호출함.

• Tool Dispatcher: 요청을 특정 도구(예: trading_kline, trading_macd)로 라우팅함.

• MarketDataClient: 통합 시장 데이터 액세스 계층, 현재 Akshare 기반으로 구현되었으며 프록시 패치를 지원함.

• IndicatorEngine: TA-Lib 또는 내장 알고리즘을 호출하여 기술 지표를 계산함.

• Response Formatter: 구조화된 데이터를 Markdown 또는 JSON MCP 응답 형식으로 변환함.

• Local Cache/Storage: API 호출을 줄이기 위해 단기 캐싱 및 과거 데이터 저장에 사용됨.

시퀀스 다이어그램(Sequence Diagram)

sequenceDiagram
  participant U as Client/User
  participant M as MCP Server
  participant D as Tool Dispatcher
  participant MD as MarketDataClient
  participant I as IndicatorEngine
  participant F as Formatter

  U->>M: 发起 trading_macd 请求 (symbol, start, end, params)
  M->>D: 解析并转发请求
  D->>MD: 请求历史 K 线 (symbol, start, end)
  MD-->>D: 返回原始行情数据 (OHLCV)
  D->>I: 传入行情数据与参数, 调用指标计算
  I-->>D: 返回指标结果 (MACD lines, histogram)
  D->>F: 格式化为 Markdown / JSON 的 MCP 响应
  F-->>M: 返回格式化结果
  M-->>U: 通过 HTTP Stream 返回响应 (chunked / 完整)

  alt 缓存命中
    D->>Storage: 读取缓存
    Storage-->>D: 返回缓存数据
  end

  alt 第三方被阻断/需要代理
    MD->>Proxy: 走 akshare-proxy-patch
    Proxy-->>MD: 返回代理后的数据
  end

위의 두 다이어그램은 현재 시스템의 추상적인 뷰입니다. 다이어그램을 더 많은 구성 요소(예: 인증, 속도 제한, 큐, 비동기 작업, 모니터링 지표)로 세분화하고 싶다면 추가할 부분을 알려주세요. Mermaid 다이어그램을 확장하고 README를 업데이트하겠습니다.

이 업데이트가 괜찮다면 변경 사항을 새 브랜치에 커밋하고 푸시한 다음, 검토를 위해 Pull Request를 생성하겠습니다.