Skip to main content
Glama
ianlyoo

K-invest

by ianlyoo
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

K-invest

내 증권 계좌를 아는 read-only MCP 서버 — 웹 LLM에 개인 투자 컨텍스트를 연결한다

English · MIT License · Python 3.10+ · CI

ChatGPT, Claude, Perplexity 같은 웹 LLM은 내 계좌·보유 종목·매매 내역을 모른다. K-invest는 토스증권, 한국투자증권(KIS), SEC EDGAR, yfinance, Binance USD-M 선물을 하나의 MCP(Model Context Protocol) 서버로 묶어, LLM이 내 투자 데이터를 조회 전용으로 참조하며 답하게 만든다.

주문 생성·정정·취소 도구는 없다. 모든 엔드포인트가 read-only다.

아키텍처

flowchart LR
    A[Claude / ChatGPT / Perplexity] -- "HTTPS + Bearer" --> B[K-invest<br/>FastMCP · Streamable HTTP]
    B --> C[Toss Securities]
    B --> D[KIS Open API]
    B --> E[SEC EDGAR]
    B --> F[yfinance]
    B --> G[Binance USD-M Futures]
    B -.optional.-> H[margin-ta 기술적 분석]

Related MCP server: tossinvest-mcp

빠른 시작

방법 1 — clone & run

git clone https://github.com/ianlyoo/K-invest && cd K-invest
pip install -r requirements.txt
cp .env.example .env   # MCP_AUTH_TOKEN과 provider credential 채우기
python3 server.py      # 127.0.0.1:8100 에서 기동

방법 2 — pip 설치

pip install git+https://github.com/ianlyoo/K-invest   # venv/pipx/uv 격리 설치 권장
k-invest

flat 모듈 패키징이라 최상위 모듈명(server 등)이 설치된다. 반드시 가상환경에 설치할 것.

provider는 부분 설정이 가능하다. Toss만 설정해도 서버는 뜨고, 미설정 provider의 도구는 KIS_NOT_CONFIGURED 같은 에러 envelope을 반환한다.

도구 카탈로그

시세/시장 데이터

도구

설명

get_quote(symbol)

토스 현재가

get_orderbook(symbol)

토스 호가

get_recent_trades(symbol)

토스 최근 시장 체결

get_price_limits(symbol)

상/하한가. 응답의 기준일/세션은 provider 필드와 함께 해석해야 합니다.

get_candles(symbol, interval="1d", count=100)

1d 또는 1m 캔들

get_stock_info(symbol)

종목 기본 정보

get_stock_warnings(symbol)

매수 유의사항

get_exchange_rate(base="USD", quote="KRW")

환율

`get_market_hours(market="US"

"KR")`

get_kis_domestic_quote(symbol)

KIS 국내 시세

get_kis_overseas_quote(symbol, exchange)

KIS 해외 시세. 일본은 TKSE/TSE를 허용하고 내부 KIS 코드는 TSE를 사용합니다.

compare_quotes(symbol, exchange="NASDAQ")

토스/KIS 시세 비교와 provider 경고

암호화폐 선물 데이터

Binance USD-M Futures 공개 market-data 엔드포인트만 사용합니다. API 키가 필요 없고, 주문/레버리지/마진/이체 기능은 노출하지 않습니다.

도구

설명

get_binance_futures_quote(symbol)

최신 선물 가격. 예: BTCUSDT, ETHUSDT

get_binance_futures_mark_price(symbol)

mark price, index price, latest funding rate

get_binance_funding_rate(symbol, limit=10)

펀딩비 히스토리. funding_rate_pct 포함

get_binance_open_interest(symbol, history=false, period="1h", limit=30)

현재 open interest 또는 최근 1개월 범위 히스토리

get_binance_futures_candles(symbol, interval="1h", count=100, price_type="last")

last price 또는 mark price 기준 선물 캔들

get_crypto_futures_snapshot(symbol)

가격, mark/index, 펀딩비, open interest 요약

get_crypto_futures_snapshot("BTCUSDT") 예시:

{
  "symbol": "BTCUSDT",
  "market": "binance_usd_m_futures",
  "auth_required": false,
  "quote": {"price": 60000.5},
  "mark": {"mark_price": 60010.25, "last_funding_rate_pct": 0.01},
  "funding_rates": [{"funding_rate_pct": 0.01}],
  "open_interest": {"open_interest": 123.45},
  "open_interest_notional": 7408265.3625
}

계좌/포트폴리오 조회

도구

설명

get_toss_accounts()

설정된 토스 계좌 label 목록. credential 값은 반환하지 않습니다.

get_toss_holdings(symbol="", account="primary")

토스 보유 종목. account는 primary, secondary, all

`get_toss_buying_power(currency="USD"

"KRW", account="primary")`

get_toss_trade_history(limit=50, account="primary")

토스 최근 체결 내역. account="all" 지원

get_kis_domestic_balance()

KIS 국내 잔고

get_kis_overseas_balance()

KIS 해외 잔고

get_kis_trade_history(start_date, end_date)

KIS 체결 내역

get_kis_cash_balance()

KIS 현금 잔고

get_portfolio_risk(detail_level="summary")

토스/KIS 보유종목을 best-effort로 모아 통화별 노출과 집중도 리스크를 계산

재무/공시

도구

설명

get_financials(symbol)

yfinance 재무제표/밸류에이션. 비율은 _pct, 기간은 period_type/period_end로 표기합니다.

get_key_metrics(symbol)

주요 밸류에이션/수익성/성장률 지표. yfinance 포워드 EPS/매출 추정, 목표가, 추천 컨센서스를 포함합니다.

get_sec_financials(symbol)

SEC CompanyFacts 10-K 연간 재무 + 10-Q 분기 + 최근 4개 회계분기 TTM

get_ttm_financials(symbol)

SEC 10-Q/FY 기반 TTM 요약과 최근 분기 목록

get_insider_trades(symbol, days_back=180, detail_level="summary")

SEC Form 4 내부자 거래. 기본은 요약/집계이며 full에서만 raw lot을 포함합니다.

get_risk_free_rate()

yfinance ^TNX 기반 10Y 미국채 금리

get_sec_financials SEC 확장 블록 예시:

{
  "quarters": [{"fiscal_year": 2026, "fiscal_period": "Q2", "revenue": {"value": 10599000000}}],
  "ttm": {
    "period_type": "TTM",
    "revenue": {"value": 44487000000},
    "operating_income": {"value": 11355000000},
    "operating_cash_flow": {"value": 14285000000},
    "capex": {"value": 1783000000},
    "free_cash_flow": {"value": 12502000000}
  },
  "segment_revenue": {
    "latest_quarter": [
      {"segment": "qct", "value": 9076000000},
      {"segment": "qtl", "value": 1382000000},
      {"segment": "handsets", "value": 6024000000}
    ]
  },
  "annuals": [{"earnings_quality": {"normalization_flags": ["high_effective_tax_rate"]}}]
}

get_key_metrics 컨센서스 예시:

{
  "analyst_consensus": {
    "forward_eps": 10.9653,
    "target_price": {"mean": 215.42, "median": 220.0},
    "recommendation": {"key": "hold", "mean": 2.51},
    "revenue_estimate": {"+1y": {"avg": 43579002120, "growth_pct": 2.37}}
  }
}

기술적 분석

도구

설명

analyze_technical(symbol, market="auto", detail_level="summary")

margin-ta 전체 분석 요약

get_entry_plan(symbol, market="auto", detail_level="summary")

추천 진입 전략/손절/목표가

scan_top_stocks(top_n=5, min_score=0)

NASDAQ100 + S&P500 기술적 스캐너. margin-ta scan_nightly.py --json 사용

MARGIN_TA_HOME 미설정 시 MARGIN_TA_NOT_CONFIGURED 에러를 반환하는 선택 기능입니다.

margin-ta 한국 종목은 KRW 호가 단위에 맞게 진입가/손절가/목표가를 반올림합니다. entry_tranche_pct는 전술적 진입 tranche 크기이며 전체 포트폴리오 비중 권고가 아닙니다. 첫 목표가 기준 R:R이 낮으면 quality/confidence를 낮추고 경고를 반환합니다.

복합/운영 도구

도구

설명

get_stock_snapshot(symbol, market="auto")

시세 비교, 주요 지표, 내부자 요약, 기술적 진입 계획을 한 번에 반환

get_portfolio_risk(detail_level="summary")

포트폴리오 통화 노출/집중도 리스크

health_check()

토스/KIS/SEC/yfinance/margin-ta 경량 상태 점검

get_invest_mcp_help(topic="overview")

LLM용 사용 가이드

인터넷 노출 (HTTPS)

MCP 커넥터는 HTTPS가 필요하다. 고정 IP만 있으면 sslip.io와 Caddy로 도메인 없이 노출할 수 있다:

# /etc/caddy/Caddyfile — <your-ip>를 서버 공인 IP로 치환
<your-ip>.sslip.io {
    reverse_proxy 127.0.0.1:8100
}

.env에 MCP_PUBLIC_URL=https://<your-ip>.sslip.io를 설정한다 (DNS rebinding 보호 allowlist가 이 값에서 유도된다).

LLM 클라이언트 연결

  • Claude (Pro/Max/Team): 설정 → Connectors → Add custom connector → URL은 공개 URL 뒤에 /mcp를 붙인 값 (https://<your-ip>.sslip.io + /mcp), Authorization에 MCP_AUTH_TOKEN 값

  • ChatGPT (Pro/Business): 설정 → Connectors → MCP 서버 추가 — 동일 URL/토큰

설정 레퍼런스

환경변수

필수

설명

MCP_AUTH_TOKEN

✅

Bearer 토큰. openssl rand -hex 32로 생성

MCP_PUBLIC_URL

외부 접근 URL (기본 http://127.0.0.1:8100)

TOSS_CLIENT_ID / TOSS_CLIENT_SECRET

✅*

토스증권 Open API (WTS → 설정 → Open API)

TOSS_CREDS_FILE

다중 계좌 JSON ({"accounts": [...]}, chmod 600)

KIS_APP_KEY / KIS_APP_SECRET

KIS Open API (발급)

KIS_CANO / KIS_ACNT_PRDT_CD

KIS 계좌번호 8자리 / 상품코드 2자리

KIS_ENV_FILE

APP_KEY 등이 든 기존 env 파일 재사용

SEC_USER_AGENT

SEC 권장 UA — 연락 가능한 이메일 포함

MARGIN_TA_HOME

margin-ta 체크아웃 경로 (기술적 분석 3종 활성화)

KINVEST_CACHE_DIR

토큰 캐시 디렉토리 (기본 ~/.cache/k-invest)

* Toss 또는 KIS 중 최소 하나. 나머지는 선택.

응답 규약

모든 도구는 {ok, data, error, meta} envelope을 반환한다:

{"ok": true, "data": {...}, "error": null,
 "meta": {"server_version": "2.0.0", "provider": "toss"}}

실패 시 error.code(KIS_NOT_CONFIGURED, UPSTREAM_TOSS_ERROR 등)·provider· retryable이 채워진다. provider 간 시세 차이는 정상일 수 있다 — 거래소·세션·지연이 달라서이며, compare_quotes류 도구는 경고 필드로 이를 명시한다.

보안

  • READ-ONLY 불변식: 주문 관련 도구는 등록되지 않는다. PR로도 받지 않는다.

  • credential은 env/파일로만 주입되고 응답에 노출되지 않는다. creds 파일은 chmod 600.

  • MCP_AUTH_TOKEN 없이는 서버가 기동을 거부한다.

  • 인터넷 노출 시: 강한 토큰, HTTPS 필수, 방화벽에서 8100 직접 노출 금지(리버스 프록시만).

systemd 상시 구동 (선택)

deploy/k-invest.service 템플릿의 placeholder(youruser 등)를 바꿔 /etc/systemd/system/에 설치하고, env는 /etc/k-invest.env에 둔다.

margin-ta (선택)

analyze_technical/get_entry_plan/scan_top_stocks는 별도 기술적 분석 엔진 [margin-ta]의 로컬 체크아웃이 필요하다 (MARGIN_TA_HOME). margin-ta는 곧 별도 리포로 공개 예정이며, 그때까지 이 3개 도구는 선택 기능이다.

개발

python3 -m pytest tests/   # 테스트
ruff check .               # 린트

Disclaimer

모든 출력은 투자 판단 보조용 데이터이며 매매 권고가 아니다. 데이터 정확성·지연에 대한 보증이 없고, 사용에 따른 손실은 사용자 책임이다.

License

MIT © 2026 AhnRyu

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ianlyoo/K-invest'

If you have feedback or need assistance with the MCP directory API, please join our Discord server