FinMind-MCP

FinMind 官方 Model Context Protocol server。 讓 Claude、Gemini CLI、Cursor、Windsurf 等支援 MCP 的 AI 工具，能用自然語言查 FinMind 75+ 種台股、期權、總經與全球金融資料。

倉庫同時收錄 FinMind Custom GPT 的 OpenAPI Action schema 與 編譯 instructions 工具——MCP server 與 Custom GPT 共用一份知識包 （knowledge/）。

快速開始

# 取 Token: https://finmindtrade.com/analysis/#/account/user
export FINMIND_TOKEN=your-token

# 一行裝
uvx finmind-mcp
# 或
pipx install finmind-mcp

在各 host 啟用

Windows 使用者：請先看 install/windows.md —— 含 uv/pipx 安裝、PowerShell 環境變數、各 host 設定檔的 Windows 路徑，以及「host 找不到 finmind-mcp 指令」等常見問題。

Tools

權限不足時，工具會說明該 dataset／endpoint 需要哪個方案（Backer / Sponsor / Sponsor Pro）、附上 API 回應原文與升級連結；參數錯誤時同樣附上 API 原文。

財報 PDF（download_financial_report）

• 給股票代號、西元年、季別（年報只要年份），工具會下載 PDF 並先回封面與目錄；AI 接著依目錄用 pages 讀附註，或用 keyword（例如「存貨」「營業收入」）直接找頁面。不用另外裝讀 PDF 的工具。
• 營收依產品／地區／技術平台／製程的細分、存貨組成、轉投資處分這類資訊只在財報附註裡，結構化財報資料集沒有。
• 檔案存在 finmind-mcp/financial_report_file/ 下（與整日檔同一個快取根目錄），同一份再查直接用本機檔。
• 一次最多回傳約 30,000 字。部分 PDF 的主要報表頁是影像、部分年報文字層損壞，這些頁面工具會標出來、不回亂碼；主要報表數字請用 query_dataset 查三大報表。

整日檔下載（download_storage_object）

• 檔案存到 FINMIND_DOWNLOAD_DIR；沒設時預設為使用者快取目錄下的 finmind-mcp/storage_objects/（Linux ~/.cache/…、macOS ~/Library/Caches/…、Windows %LOCALAPPDATA%\…）。同一天同一 dataset 再查會直接用本機檔，refresh: true 才重抓。

• 整日檔動輒數十 MB，工具只回摘要（最多 500 列），完整資料請用程式讀本機檔（pandas.read_parquet(path)）。

• 讀 parquet 需要 pyarrow（wheel 約 29–54 MB），是選用 extra，預設不裝；沒裝時仍會下載並回傳路徑，並提示安裝方式：

  uvx --from "finmind-mcp[parquet]" finmind-mcp      # host 設定的 args 改成 ["--from", "finmind-mcp[parquet]", "finmind-mcp"]
  pipx install "finmind-mcp[parquet]"
  

  Claude Desktop 擴充套件（.mcpb）已內含 pyarrow，不需另外處理。

範例查詢

• 「台積電最近一個月股價」
• 「2330 三大法人近一週買賣」
• 「台積電今年每月營收」
• 「美元對台幣匯率近半年走勢」
• 「合庫（1020）7/1~7/5 每天買賣台積電多少張」（分點統計）
• 「台積電跟加權指數現在多少」（即時快照）
• 「下載 10/16 全市場分 K 整日檔，給我台積電的部分」（整日檔，Sponsor Pro）

完整範例見 knowledge/examples.md。

倉庫結構

FinMind-MCP/
├── src/finmind_mcp/      # MCP server source
├── tests/                # pytest 單元測試（全 mock）
├── smoke.py              # stdio smoke test
├── knowledge/            # SSOT markdown（dataset、行為規則、錯誤腳本、Q&A）
├── chatgpt/              # Custom GPT artifacts（OpenAPI + build script）
├── install/              # 各 host 安裝指引
├── mcpb/                 # Claude Desktop 擴充套件（.mcpb）的 manifest 與進入點
└── docs/                 # 設計 spec 與實作 plan

開發

uv venv --python 3.10
source .venv/bin/activate
uv pip install -e ".[dev]"   # dev extra 含 respx 與 pyarrow
uv run pytest -v
FINMIND_TOKEN=... uv run python regression/runner.py   # 打 live API 的契約測試
uv run python smoke.py    # stdio integration check

發佈

兩條 distribution（MCP 與 ChatGPT）共用一份 knowledge/，但發佈方式不同。

MCP server（Claude / Gemini / Cursor / Windsurf 線）— 推 tag 全自動

改完 knowledge/ 或程式碼後，推一個版本 tag 就好：GitHub Actions（.github/workflows/publish.yml）會自動 uv build → twine check → 用 PyPI Trusted Publishing（OIDC）發 PyPI。版本號由 tag 經 hatch-vcs 決定，不用改 pyproject.toml。

uv run pytest -q          # 先確認測試過（CI 也會再跑一次）
git tag v0.1.0
git push origin v0.1.0    # → CI 自動 build + 發 PyPI

PyPI 發佈成功後，同一個 workflow 會打包 Claude Desktop 擴充套件 finmind.mcpb（finmind-mcp 釘在同一版本）並附加到該 tag 的 GitHub Release，下載連結 releases/latest/download/finmind.mcpb 會自動指向最新版。本機打包測試：

python3 scripts/build_mcpb.py --dev   # 需要 Node.js；--dev 用本機原始碼
python3 scripts/check_mcpb.py         # 模擬 Claude Desktop 解壓、啟動、MCP 握手

新增 tool 時記得同步 mcpb/manifest.json 的 tools（tests/test_mcpb.py 會擋）。

knowledge/ 由 hatch force-include 打包進 wheel（finmind_mcp/_knowledge/），server runtime 直接讀、不用 compile；發版後用戶 uvx finmind-mcp / pipx install finmind-mcp 即抓到新版。

首次需在 PyPI 設好 trusted publisher（project finmind-mcp / repo FinMind/FinMind-MCP / workflow publish.yml / env pypi）。

Custom GPT（ChatGPT 線）— 產物自動 build、建 GPT 手動

GPT 的輸入由 chatgpt/build_instructions.py 編出來，CI 每次 push/PR 都會驗證它能 build 且 instructions 在 8000 字上限內。但 OpenAI 沒有公開 API 可程式化建立／更新 Custom GPT，最後一步要手動在 ChatGPT builder 完成：

python chatgpt/build_instructions.py
# 產出（gitignored，每次重生）：
# - chatgpt/instructions.txt      → 貼到 Custom GPT 的 instructions
# - chatgpt/knowledge_bundle.md   → 上傳到 Custom GPT 的 Knowledge files
# - chatgpt/openapi.yaml          → 在 Custom GPT Action 匯入（Bearer auth）

knowledge/ 改版後重跑上面指令、把三個檔重貼／重傳到 GPT 即可。各 host 的 MCP 安裝方式見 install/*.md。

License

Apache License 2.0。