Finviz MCP

Finviz MCP

MCP 서버로, Claude(또는 모든 MCP 클라이언트)에게 Finviz 주식 데이터(개별 주식 지표, 뉴스, 스크리너 검색) 및 실제 과거 가격 데이터(Yahoo Finance)에 대한 접근을 제공합니다. 데이터는 finvizfinance 및 yfinance 라이브러리를 통해 실시간으로 가져오므로 API 키가 필요하지 않습니다.

도구

• get_stock(ticker) – 개별 주식의 Finviz 지표(P/E, 시가총액, 마진, 수익 등)

• get_stock_news(ticker) – 해당 주식의 최근 뉴스 헤드라인

• get_price_history(ticker, days=7) – Yahoo Finance의 실제 일일 과거 데이터(시가/고가/저가/종가/거래량) 최대 365일, 그리고 최고의 매수일(최저 가격 및 최근 종가 대비 최고 수익)에 대한 분석이 포함됩니다. Finviz 자체에는 과거 데이터 API가 없으며, 현재 스냅샷과 정적 차트 이미지만 제공합니다.

• screen_stocks(...) – 자연어 매개변수(market_cap, sector, pe_max, rsi, dividend_yield_min, signal, ...)를 사용한 Finviz 스크리너. Claude에게 Finviz의 내부 필터 이름을 설명할 필요가 없습니다. 서버가 매개변수를 자동으로 가장 가까운 지원 값으로 변환합니다. 로컬에서만 실행 가능하며, 클라우드 서버에 배포할 수 없습니다 – 제한 사항 참조.

• list_screener_filters(search=None) / list_screener_signals() – Claude가 screen_stocks에 명명된 매개변수로 아직 포함되지 않은 필터가 필요할 경우를 위한 도우미입니다. 찾은 값은 screen_stocks(extra_filters={...}) 매개변수로 제공할 수 있습니다.

screen_stocks 매개변수는 항상 가장 가까운 Finviz 제공 "버킷"으로 스냅됩니다(예: pe_max=18 → "Under 20"). Finviz 스크리너는 미리 정의된 값 범위만 지원하고 임의의 숫자는 지원하지 않기 때문입니다.

1. 로컬 테스트

Python 3.10+ 필요:

pip install -r requirements.txt
python server.py

서버가 http://localhost:8000/mcp(Streamable HTTP)에서 시작됩니다.

이 환경에서 종단 간 테스트 완료(설치, 시작, initialize 핸드셰이크 및 실제 Finviz 데이터를 사용한 5개 도구 모두). 테스트 중 PyPI의 finvizfinance 1.3.0이 Finviz의 업데이트된 페이지 템플릿을 아직 따라잡지 못한 것으로 나타났습니다. get_stock이 완전히 중단되었고(이전 quote-links CSS 클래스가 이제 quote-header_categories로 변경됨, 내용도 다름), screen_stocks의 종목 열에 추가 문자가 있었습니다(예: "NVDA" → "NNVDA", Finviz의 새 로고 자리 표시자로 인해). server.py가 두 가지를 모두 직접 수정합니다(파일 상단 주석 참조). Finviz가 페이지를 다시 변경하면 이러한 수정 사항을 가장 먼저 확인해야 합니다.

로컬에 Python이 없고 Docker가 있는 경우 로컬 Python 설치 없이도 테스트할 수 있습니다:

docker build -t finviz-mcp .
docker run -p 8000:8000 finviz-mcp

명령줄에서 빠른 기능 테스트(curl 필요, 서버 실행 중이어야 함):

curl -X POST http://localhost:8000/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}"

응답에 get_stock, get_stock_news, get_price_history, screen_stocks, list_screener_filters, list_screener_signals의 6개 도구가 표시되어야 합니다.

2. 배포 (예: Render)

1. 이 디렉토리를 자신의 Git 리포지토리(GitHub/GitLab)에 푸시합니다.

2. Render → New + → Web Service → 리포지토리 연결.

3. Render가 Dockerfile을 자동으로 감지합니다. 별도의 환경 변수가 필요하지 않습니다. 서버는 Render가 설정한 PORT 변수에서 포트를 읽습니다.

4. 배포 후 https://finviz-mcp.onrender.com과 같은 URL을 받게 됩니다. MCP 엔드포인트는 그 뒤에 /mcp가 붙습니다: https://finviz-mcp.onrender.com/mcp.

Railway, Fly.io 등도 동일한 원리로 작동합니다(Dockerfile 기반 Python 호스팅, PORT 환경 변수).

3. Claude에 연결

Claude → Settings → Connectors → Add custom connector → MCP URL(https://<your-address>/mcp)을 붙여넣습니다.

Claude는 Streamable HTTP를 통한 원격 MCP 서버를 지원하므로, 이대로 작동합니다.

4. 예제 프롬프트

• "Get me the Finviz fundamentals for NVDA."

• "Find oversold technology stocks with market cap over $10B."

• "Show me 15 large-cap dividend stocks with yield over 4% and P/E under 20."

• "What's the latest news on TSLA?"

• "Find stocks flagged as Top Gainers today with average volume over 1M."

제한 사항

• screen_stocks(및 list_screener_filters/list_screener_signals)는 클라우드 서버에 배포된 상태에서 작동하지 않습니다(Render에서 테스트 완료): Finviz가 데이터 센터 IP 주소에서 스크리너 엔드포인트(finviz.com/screener.ashx)에 대해 403 Forbidden을 반환합니다. get_stock/get_stock_news/get_price_history는 동일한 서버에서 완전히 정상적으로 작동하지만(덜 보호된 다른 엔드포인트를 사용함), HTTP 헤더를 조정해도 해결할 수 없었습니다. 이는 스크리너에 대한 Finviz의 의도적인 데이터 센터 IP 차단으로 보입니다. screen_stocks 기능이 필요하면 서버를 로컬에서 실행하고(python server.py) cloudflared/ngrok 터널을 통해 연결하여 요청이 홈 네트워크 IP에서 나가도록 하십시오.

• 데이터는 Finviz/Yahoo Finance 웹사이트에서 스크래핑되므로(공식 API 키 없음), 사이트 구조가 변경되면 작동이 중단될 수 있습니다.

• screen_stocks는 요청 속도를 유지하기 위해 결과를 기본적으로 20개, 최대 50개 행으로 제한합니다.

• get_price_history는 days 매개변수를 최대 365일로 제한합니다.

• 인증 기능이 포함되어 있지 않습니다. 서비스가 공개 인터넷에 노출되면 URL을 아는 사람은 누구나 호출할 수 있습니다. 데이터는 공개 데이터이지만, 나중에 유료/제한 기능을 추가할 경우 이 점을 염두에 두십시오.