stockdata-mcp

주식 리서치를 위한 MCP 서버입니다. 두 개의 백엔드, 하나의 도구 인터페이스.

이 구분은 의도적입니다. Qualtrim은 FMP의 고객입니다. 원시 데이터를 구매해서 그 위에 레이어를 추가합니다. 그래서 이 서버는 원시 데이터가 필요하면 FMP에 직접 접근하고, Qualtrim 호출은 오직 Qualtrim만의 고유 기능에만 사용합니다.

도구 52개 — FMP 30개, Qualtrim 22개.

Qualtrim 백엔드를 활성화하기 전에

이 서버의 FMP 절반은 평범합니다. 문서화된 공개 API, 가입해서 받는 키, 원하는 대로 사용하면 됩니다.

Qualtrim 절반은 그렇지 않습니다. Qualtrim은 API를 공개하지 않습니다 — 해당 경로는 그들이 배포한 JavaScript에서 읽어낸 것이며, 서비스 약관은 플랫폼 리버스 엔지니어링과 사전 서면 동의 없이 자동화된 수단으로 데이터를 수집하는 행위를 모두 금지합니다.

그 동의는 양도할 수 없으며 이 저장소가 부여하지 않습니다. Qualtrim 백엔드를 실행하려면 자체 유료 Qualtrim 계정 그리고 Qualtrim으로부터 직접 받은 서면 허가가 필요합니다. support@qualtrim.com으로 직접 문의하세요.

그렇지 않으면 QUALTRIM_USERNAME/QUALTRIM_PASSWORD를 설정하지 않은 채 서버를 실행하세요. FMP 도구는 단독으로도 정상 작동하며 여기의 어떤 것도 Qualtrim에 의존하지 않습니다.

이 코드는 그러한 클라이언트가 어떻게 구성되는지에 대한 참고용으로 공개된 것이지, 남의 서비스에 연결하라는 초대가 아닙니다. Qualtrim이 명시한 위반 조치는 계정 해지이며, 요금은 환불되지 않습니다.

설치

cd ~/Projects/stockdata-mcp
uv venv && uv pip install -e .
./scripts/set-credentials.sh          # prompts; password input is hidden

set-credentials.sh는 0600 권한으로 .env를 작성합니다. 이 파일은 gitignore되어 있습니다. 무료 FMP 키는 https://site.financialmodelingprep.com/developer/docs에서 받으세요.

머신의 모든 세션에서 사용하려면 한 번만 등록하세요:

claude mcp add stockdata --scope user -- ~/Projects/stockdata-mcp/.venv/bin/stockdata-mcp

-e 플래그는 필요 없습니다 — 서버가 .env를 직접 읽으므로 자격 증명이 ~/.claude.json에 남지 않습니다. 실제 환경 변수는 여전히 파일을 덮어쓰므로, 원한다면 MCP 클라이언트가 -e를 전달할 수도 있습니다.

어느 세션에서든 backend_status로 확인할 수 있습니다.

모델을 위한 안내

서버는 MCP 프로토콜을 통해 자체 사용 지침을 제공합니다 — 백엔드 선택, 무료 티어 제한, Qualtrim의 특이한 동작, 수치 보고 방법. 모든 MCP 클라이언트는 별도의 설정 없이 이를 자동으로 받습니다.

연구 워크플로를 더 심층적으로 다루는 더 상세한 스킬이 .claude/skills/stock-research/에도 있습니다. Claude Code는 ~/.claude/skills/에서 이를 읽습니다(거기에 심링크하세요). Claude Desktop은 스킬을 자체 위치에서 관리하므로 그 디렉터리에서 가져오지 않습니다 — 의사 결정에 중요한 부분을 담고 있는 위의 서버 지침에 의존합니다.

Related MCP server: StocksMCP

캐싱 및 예산

응답은 ~/.cache/stockdata-mcp/cache.db의 SQLite 저장소에 캐시됩니다. 이 저장소는 클라이언트별이 아니라 전역(global)입니다 — 이 사용자의 모든 서버 프로세스가 같은 파일을 열므로 Claude Code와 Claude Desktop이 하나의 캐시와 하나의 일일 합계를 공유합니다. 이는 효율성만을 위한 것이 아니라 정확성을 위해 필요합니다. FMP 할당량은 API 키에 속하며 두 앱 모두 같은 키를 사용합니다.

TTL은 엔드포인트별로 결정됩니다. 시세(quote)는 1분, 프로필은 1주일, 참조 데이터는 1개월입니다. 날짜 범위가 오늘 이전에 끝난 과거 봉(bar)은 절대 만료되지 않습니다, 이미 발생한 종가는 바뀔 수 없기 때문입니다. 오늘까지 이어지는 범위는 여전히 움직이는 경계를 가지므로 15분이 적용됩니다.

다음 세 가지 도구가 이를 관리합니다:

estimate_cost가 존재하는 이유는 도구-요청 비율이 1:1이 아니며 호출자 쪽에서는 보이지 않기 때문입니다. fmp_search는 요청 2개를, fmp_price_target은 3개를, fmp_quote는 무료 키에서 심볼당 1개를 발생시킵니다. 최악의 경우 요청 수, 이미 캐시된 구간(leg) 수, 오늘의 잔여 예산 대비 순(net) 요청 수를 보고합니다. 검증 완료: 혼합된 5회 호출 계획에서 예측이 실제 지출과 정확히 일치했으며, 같은 계획을 웜(warm) 상태로 다시 실행했을 때는 0을 반환했습니다.

동일한 심볼을 동시에 요청하는 6개의 독립 프로세스에 걸쳐 측정한 결과: 업스트림 요청 1개, 캐시 히트 5개, 잠금 경합 없음.

구성

FMP 도구

검색 및 참조: fmp_search, fmp_profile, fmp_quote, fmp_peers, fmp_reference.

펀더멘털: fmp_income_statement, fmp_balance_sheet, fmp_cash_flow, fmp_key_metrics, fmp_ratios, fmp_financial_growth, fmp_financial_scores, fmp_revenue_segmentation, fmp_enterprise_values.

애널리스트 및 밸류에이션: fmp_analyst_estimates, fmp_price_target, fmp_grades, fmp_dcf.

이벤트 및 시장: fmp_dividends, fmp_earnings, fmp_earnings_calendar, fmp_historical_prices, fmp_technical_indicator, fmp_screener, fmp_market_movers, fmp_sector_performance, fmp_insider_trading, fmp_news.

fmp_request(endpoint, params)는 전용 래퍼 없이 FMP의 약 250개 안정 엔드포인트 — ETF 보유 내역, 13F, 상원 의원 거래, 경제 지표, SEC 제출 서류, 회의록 — 에 접근할 수 있습니다.

무료 티어가 실제로 포함하는 것

실제 무료 키로 검증한 결과: 29개 도구 중 22개가 작동합니다.

유료 플랜 필요: fmp_screener, fmp_reference, fmp_news, fmp_insider_trading, fmp_technical_indicator. 각각 원인으로 해당 플랜을 지목하는 명확한 오류를 반환합니다.

참고 사항 두 가지:

• 다중 심볼 fmp_quote는 일괄(batch) 경로가 유료이므로 심볼별 요청으로 대체됩니다. 일일 할당량을 보호하기 위해 20개 심볼로 제한됩니다.

• fmp_technical_indicator가 유료인 것은 쉽게 우회할 수 있습니다 — fmp_historical_prices는 무료이므로 지표를 OHLCV에서 로컬로 계산할 수 있습니다.

무료 티어는 하루 약 250회의 요청을 허용합니다. limit과 from_date/to_date를 전달하세요. 가격 이력의 기본값은 전체 시계열입니다.

Qualtrim 도구

심볼별: qualtrim_overview, qualtrim_profile, qualtrim_quote, qualtrim_dcf, qualtrim_kpi_charts, qualtrim_chart, qualtrim_ai_analysis, qualtrim_analyst_estimates.

비교: qualtrim_available_kpis, qualtrim_compare.

내 계정: qualtrim_portfolios, qualtrim_portfolio, qualtrim_portfolio_look_through_earnings, qualtrim_portfolio_ai_analysis, qualtrim_portfolio_dividends, qualtrim_watchlists, qualtrim_watchlist, qualtrim_dip_finder, qualtrim_watchlist_valuation_ranges.

탈출구: qualtrim_request(path), GET 전용.

쓰기 도구(qualtrim_add_watchlist_stock, qualtrim_add_portfolio_holding)는 QUALTRIM_ENABLE_WRITES=true가 아니면 실행을 거부합니다.

Qualtrim 인증의 실제 작동 방식

배포된 번들은 bearer-token 인증처럼 보입니다 — localStorage의 authTokens, Authorization: Bearer. 하지만 실제로는 그렇지 않습니다. 로그인은 사용자 객체를 반환하고 Express 세션 쿠키 (connect.sid)를 설정합니다. 일반 요청을 승인하는 것은 바로 그 쿠키입니다. 번들의 토큰 경로는 오직 refresh 호출에서만 사용됩니다.

이 클라이언트는 쿠키 저장소(cookie jar)를 유지하고, 세션을 ~/.cache/stockdata-mcp/qualtrim-session.json(0600)에 캐시하며, 401 응답 시 자동으로 다시 로그인합니다.

알려진 드리프트

배포된 백엔드는 이미 경로를 읽어낸 번들과 달라졌습니다:

두 도구 모두 이미 작동하는 변형을 사용합니다. 시간이 지나면서 이런 일이 더 많아질 것입니다 — Qualtrim 도구의 404는 경로가 이동했다는 뜻이지 티커가 잘못되었다는 뜻이 아닙니다.

qualtrim_dcf가 빈 값을 반환하는 것은 실패가 아닙니다. 계정에 해당 심볼에 대한 DCF가 저장되어 있지 않다는 뜻입니다.

Qualtrim과 서비스 약관

Qualtrim은 API를 공개하지 않습니다. 이 경로들은 그들이 배포한 JavaScript에서 읽어낸 것입니다. 두 가지 결과가 있습니다:

예고 없이 깨질 수 있습니다. 위의 "알려진 드리프트"를 참고하세요 — 이미 그렇게 되었습니다.

약관에 의해 제한됩니다. 허용 사용(acceptable-use) 조항은 사전 서면 동의 없이 자동화된 수단으로 사이트에서 데이터를 체계적으로 수집하는 것을 금지하며, 별도로 플랫폼 리버스 엔지니어링도 금지합니다. 이들의 집행 수단은 계정 해지이며, 요금은 환불되지 않습니다.

동의는 얻을 수 있습니다 — 금지 조항은 동의를 조건으로 합니다. support@qualtrim.com으로 Qualtrim에 직접 문의하고 답변을 보관하세요.

여기의 기본값은 보수적입니다: 초당 1회 요청, 최대 2개 동시 요청, 브라우저와 일치하는 user agent, 기본적으로 GET만, 대량 열거 없음. 대화형 리서치 수준의 사용량으로 유지하세요.

구조

src/stockdata_mcp/
  server.py     tool definitions for both backends
  fmp.py        FMP stable-API client
  qualtrim.py   Qualtrim cookie-session client
  util.py       throttling, response trimming, .env loading
scripts/
  set-credentials.sh
.claude/skills/stock-research/SKILL.md

투자 조언이 아닙니다

자신의 연구를 위한 데이터입니다. 어느 소스도 정확성을 보장하지 않으며, 여기의 어떤 내용도 매수 또는 매도 권유가 아닙니다.