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 啟用

Host	安裝指引
Claude Desktop	install/claude-desktop.md
Claude Code	install/claude-code.md
Cursor	install/cursor.md
Windsurf	install/windsurf.md
Gemini CLI	install/gemini-cli.md
Codex CLI	install/codex.md

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

範例查詢

「台積電最近一個月股價」
「2330 三大法人近一週買賣」
「台積電今年每月營收」
「美元對台幣匯率近半年走勢」

完整範例見 knowledge/examples.md。

倉庫結構

FinMind-MCP/
├── src/finmind_mcp/      # MCP server source
├── tests/                # pytest 31 個測試
├── smoke.py              # stdio smoke test
├── knowledge/            # SSOT markdown（dataset、行為規則、錯誤腳本、Q&A）
├── chatgpt/              # Custom GPT artifacts（OpenAPI + build script）
├── install/              # 各 host 安裝指引
└── docs/                 # 設計 spec 與實作 plan

開發

uv venv --python 3.10
source .venv/bin/activate
uv pip install -e ".[dev]"
uv run pytest -v          # 31 tests
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

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。

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

finmind_mcp-0.0.5.tar.gz (38.1 kB view details)

Uploaded Jul 17, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

finmind_mcp-0.0.5-py3-none-any.whl (41.6 kB view details)

Uploaded Jul 17, 2026 Python 3

File details

Details for the file finmind_mcp-0.0.5.tar.gz.

File metadata

Download URL: finmind_mcp-0.0.5.tar.gz
Upload date: Jul 17, 2026
Size: 38.1 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for finmind_mcp-0.0.5.tar.gz
Algorithm	Hash digest
SHA256	`34806cf6e92e07b20afb8bfadd470458b9b01a4e10871bca6d0a40cbb2941ef5`
MD5	`a0642fc6e980effac7e0eef2dfe58287`
BLAKE2b-256	`e59b91ce5dcc63dd29974f8921e56415a11aa67e5efd8436634aab77ce8763e6`

See more details on using hashes here.

Provenance

The following attestation bundles were made for finmind_mcp-0.0.5.tar.gz:

Publisher: publish.yml on FinMind/FinMind-MCP

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: finmind_mcp-0.0.5.tar.gz
- Subject digest: 34806cf6e92e07b20afb8bfadd470458b9b01a4e10871bca6d0a40cbb2941ef5
- Sigstore transparency entry: 2188396482
- Sigstore integration time: Jul 17, 2026
Source repository:
- Permalink: FinMind/FinMind-MCP@6ca46822a870f150c66bb4e70e2d4e1e5ba7534f
- Branch / Tag: refs/tags/0.0.5
- Owner: https://github.com/FinMind
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@6ca46822a870f150c66bb4e70e2d4e1e5ba7534f
- Trigger Event: push