Richgo Finance

Model Context Protocol (MCP) server for public data exposed by finance.richgo.ai.

It lets MCP clients search Korean stocks, fetch Richgo stock detail data, and use Richgo's ranking, undervaluation, AI ranking, curation, refreshed market dashboard, and Korea export-data screens from an assistant.

This project only calls public Richgo Finance endpoints by default. It does not bypass authentication or scrape private account data.

Tools

• richgo_search_stock: search by Korean stock name or ticker.
• richgo_get_stock_detail: fetch public detail for a ticker.
• richgo_analyze_stock: search/alias resolve, then fetch compact analysis.
• richgo_get_scores: score ranking table.
• richgo_get_undervalued: undervalued stock tabs.
• richgo_get_ai_rankings: AI ranking tab.
• richgo_get_curation: curated screener buckets.
• richgo_get_breakout: breakout/special signal endpoint.
• richgo_get_exports_overview: Korea export overview, monthly export/import/trade balance history, sector-stock mappings, and export/employment momentum.
• richgo_get_exports_nations: country-level export/import series and trade balances.
• richgo_get_exports_region_ranking: regional export rankings and change rates.
• richgo_get_market_ticker: headline market ticker snapshot, with freshness metadata for Korean index dates.
• richgo_get_market_score_history: market environment score history.
• richgo_get_market_investor_trend: foreign/institution/pension/individual investor flow trends.
• richgo_get_market_valuation_history: market PER/PBR valuation history.
• richgo_get_market_seasonality: market seasonality distribution and trajectory.
• richgo_get_market_global_compare: global market comparison trajectories.
• richgo_get_market_dashboard: bundled refreshed start/market page data.
• richgo_get_market_api: generic /api/market/... wrapper.
• richgo_get_public_api: constrained generic /api/... wrapper.
• richgo_get_consensus_picks: merge Richgo scores, undervaluation, gap, and AI rankings into one ranked candidate list.
• richgo_build_portfolio: build an integer-share portfolio from Richgo consensus signals for a budget and risk profile.
• richgo_save_obsidian_report: save a generated portfolio report to a user-provided Obsidian vault path.
• richgo_guided_portfolio: beginner-friendly portfolio wizard that uses MCP form elicitation when the client supports it.
• richgo_service_catalog: list exposed services.

Install

Easiest: npx

After this package is published to npm, you can run it directly with npx. Add this to your MCP client config:

{
  "mcpServers": {
    "richgo-finance": {
      "command": "npx",
      "args": ["-y", "richgo-finance-mcp"]
    }
  }
}

Restart your MCP client, then ask naturally:

셀트리온 리치고 데이터로 분석해줘

Developer install

git clone https://github.com/reallygood83/rfmcp.git
cd rfmcp
npm install
npm run build

Run Locally

npm start

On the original author's Mac, Homebrew Node was broken, so this bundled Node path was used:

export PATH=/Users/moon/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin:$PATH
npm run build
npm start

Codex or Claude MCP config for local clone

{
  "mcpServers": {
    "richgo-finance": {
      "command": "node",
      "args": ["/absolute/path/to/rfmcp/dist/index.js"]
    }
  }
}

Example Prompts

You do not need to know the MCP tool names. Ask naturally:

• 아이티센글로벌 리치고 데이터로 분석해줘
• /rf 셀트리온 분석해줘
• 삼성전자와 SK하이닉스 리치고 상세 지표 비교해줘
• 리치고 저평가 total 상위 10개 보여줘
• AI 랭킹 상위 종목을 요약해줘
• 리치고 시작페이지에 새로 생긴 시장 현황 데이터를 요약해줘
• 한국 수출 데이터 기준으로 섹터와 관련 종목을 뽑아줘
• 외국인과 기관 수급 흐름을 리치고 시장 데이터로 보여줘
• 리치고 컨센서스 기준으로 오늘 투자 매력 높은 종목 10개 뽑아줘
• 500만원 중립형 포트폴리오 만들어줘
• 초보자용 리치고 포트폴리오 마법사 시작해줘
• 나는 잘 모르니까 질문하면서 300만원 투자 전략 만들어줘
• 오늘 리치고 기준으로 뭐가 제일 좋아?
• 1000만원이면 몇 종목을 몇 주씩 사면 좋을까?
• 이 결과를 내 Obsidian 볼트에 보고서로 저장해줘

Natural Language Routing

Most MCP clients choose tools from the descriptions below. These are the intended natural-language routes:

User says	Preferred tool	What happens
삼성전자 분석해줘, 005930 리치고로 봐줘	richgo_analyze_stock	Resolves the stock and returns compact Richgo detail.
저평가 상위 10개, AI 랭킹 보여줘	richgo_get_undervalued / richgo_get_ai_rankings	Returns the requested screen.
수출 데이터로 투자 전략, 한국 수출 데이터 보여줘	richgo_get_exports_overview / richgo_get_exports_nations	Returns export/import/trade-balance history and sector-stock export mappings.
시장 현황, 시장 위험도, 계절성, 수급 흐름	richgo_get_market_dashboard / market-specific tools	Returns the refreshed Richgo start/market page data bundle or focused market series.
오늘 투자 매력 높은 종목, 뭐가 좋아?, 컨센서스 픽	richgo_get_consensus_picks	Combines scores, undervaluation, gap, and AI ranking into one candidate list.
500만원 포트폴리오, 몇 주씩 살까?, 예산으로 전략 짜줘	richgo_build_portfolio	Builds an integer-share portfolio with cash balance and risks.
초보자용, 질문하면서 도와줘, 마법사 시작	richgo_guided_portfolio	Uses form elicitation when supported, then builds the portfolio.
Obsidian에 저장, 볼트에 보고서로 저장	richgo_save_obsidian_report	Saves only when a vault path is provided or configured privately.

Market ticker freshness

richgo_get_market_ticker and the ticker section inside richgo_get_market_dashboard add a freshness object. Check it before writing KOSPI/KOSDAQ values as "current" market levels.

• status: "verify_before_current_use" means the Korean index ticker date is older than the estimated latest Korea regular-session close.
• expectedLatestKoreaCloseDate is estimated in Asia/Seoul time: after 16:00 KST on weekdays it expects today's close; before then it expects the previous weekday; weekends roll back to Friday.
• Korean public holidays are not modeled, so treat the warning as a guardrail, not as an exchange-calendar substitute.

Optional Slash Command

This repo includes a Claude-style slash command template at commands/rf.md. Install it as /rf with:

mkdir -p ~/.claude/commands
cp commands/rf.md ~/.claude/commands/rf.md

After that, use prompts like:

/rf 셀트리온 분석해줘

The /rf command is tuned to produce data-backed Korean reports, not just a metric dump. It should connect revenue, profitability, cash flow, financial safety, valuation, and Richgo percentile signals into a concrete story that is easy to understand.

Portfolio and Obsidian reports

The portfolio tools intentionally do not hardcode a personal vault path. This keeps the published MCP reusable for other users.

Recommended natural-language flow:

초보자용 리치고 포트폴리오 마법사 시작해줘

If your MCP client supports form elicitation, the server asks for budget, risk profile, number of stocks, and whether to save to Obsidian. If the client does not support elicitation, call:

500만원 중립형 포트폴리오 만들어줘

To save Obsidian reports, either pass vaultPath in the tool call:

{
  "budget": 5000000,
  "riskProfile": "balanced",
  "vaultPath": "/absolute/path/to/your/vault",
  "noteDir": "Richgo"
}

Or keep the path in your private shell/MCP environment:

export RICHGO_OBSIDIAN_VAULT_PATH='/absolute/path/to/your/vault'

Do not commit personal vault paths to this repository.

Optional auth

Public endpoints work without auth. If you legitimately need login-only Richgo features, set your own cookie:

export RICHGO_COOKIE='...'

This server does not bypass authentication.

Disclaimer

Richgo Finance data is informational only and is not investment advice. Final investment decisions and responsibility belong to the user.