|
| 1 | +# Windows 安裝指引 |
| 2 | + |
| 3 | +各 host 的安裝文件（[Claude Desktop](claude-desktop.md)、[Cursor](cursor.md) 等）中的指令以 macOS / Linux 為例。Windows 使用者請先照本頁完成「安裝套件」與「設定 Token」，再回到對應 host 的文件貼設定；本頁最後整理了 Windows 常見問題（尤其是 host 顯示找不到 `finmind-mcp` 指令的狀況）。 |
| 4 | + |
| 5 | +以下指令都在 **PowerShell** 執行（開始功能表搜尋「PowerShell」開啟即可，不需系統管理員權限）。 |
| 6 | + |
| 7 | +## 1. 安裝套件 |
| 8 | + |
| 9 | +擇一即可： |
| 10 | + |
| 11 | +### 方式 A：uv（推薦，不需先安裝 Python） |
| 12 | + |
| 13 | +[uv](https://docs.astral.sh/uv/) 會自動下載並管理 Python，適合電腦上沒有 Python 的使用者： |
| 14 | + |
| 15 | +```powershell |
| 16 | +winget install --id astral-sh.uv -e |
| 17 | +# 或（沒有 winget 時） |
| 18 | +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" |
| 19 | +``` |
| 20 | + |
| 21 | +裝完後**關閉 PowerShell 再開一個新視窗**（讓 PATH 生效），驗證： |
| 22 | + |
| 23 | +```powershell |
| 24 | +uvx finmind-mcp --help |
| 25 | +``` |
| 26 | + |
| 27 | +之後各 host 設定中的 `command` 填 `uvx`、`args` 填 `["finmind-mcp"]`（首次啟動會自動從 PyPI 下載 `finmind-mcp`，不需另外安裝）。 |
| 28 | + |
| 29 | +### 方式 B：pipx（已有 Python 3.10+ 的使用者） |
| 30 | + |
| 31 | +```powershell |
| 32 | +python -m pip install --user pipx |
| 33 | +python -m pipx ensurepath |
| 34 | +``` |
| 35 | + |
| 36 | +關閉 PowerShell 再開新視窗，然後： |
| 37 | + |
| 38 | +```powershell |
| 39 | +pipx install finmind-mcp |
| 40 | +finmind-mcp --help |
| 41 | +``` |
| 42 | + |
| 43 | +之後各 host 設定中的 `command` 直接填 `finmind-mcp`。 |
| 44 | + |
| 45 | +> 還沒有 Python？可用 `winget install --id Python.Python.3.12 -e` 安裝，或到 [python.org](https://www.python.org/downloads/windows/) 下載安裝檔（安裝時記得勾選 **Add python.exe to PATH**）；或直接改用方式 A。 |
| 46 | +
|
| 47 | +## 2. 設定 Token |
| 48 | + |
| 49 | +先依 [token 取得指引](../knowledge/token-guide.md) 取得 FinMind Token。**最推薦的做法**是直接把 token 填進各 host 設定檔的 `env` 區塊（各 host 文件的設定範例都有 `FINMIND_TOKEN` 欄位），不必動系統環境變數。 |
| 50 | + |
| 51 | +若想改設成 Windows 環境變數： |
| 52 | + |
| 53 | +```powershell |
| 54 | +# 只在目前這個 PowerShell 視窗有效（適合先測試） |
| 55 | +$env:FINMIND_TOKEN = "your-token-here" |
| 56 | +
|
| 57 | +# 永久寫入使用者環境變數 |
| 58 | +setx FINMIND_TOKEN "your-token-here" |
| 59 | +``` |
| 60 | + |
| 61 | +注意 `setx` 只對**之後新開啟**的程式生效——已經開著的終端機、Claude Desktop 等應用程式都要完全關閉重開才讀得到。 |
| 62 | + |
| 63 | +## 3. Windows 設定檔路徑對照 |
| 64 | + |
| 65 | +各 host 文件中 `~` 開頭的路徑，在 Windows 對應如下（`%APPDATA%`、`%USERPROFILE%` 可直接貼進檔案總管的網址列開啟）： |
| 66 | + |
| 67 | +| Host | Windows 設定檔路徑 | |
| 68 | +|---|---| |
| 69 | +| Claude Desktop | `%APPDATA%\Claude\claude_desktop_config.json` | |
| 70 | +| Claude Code | `%USERPROFILE%\.claude.json` | |
| 71 | +| Cursor（全域） | `%USERPROFILE%\.cursor\mcp.json` | |
| 72 | +| Windsurf | `%USERPROFILE%\.codeium\windsurf\mcp_config.json` | |
| 73 | +| Gemini CLI | `%USERPROFILE%\.gemini\settings.json` | |
| 74 | +| Codex CLI | `%USERPROFILE%\.codex\config.toml` | |
| 75 | + |
| 76 | +## 4. 常見問題 |
| 77 | + |
| 78 | +### host 啟動 server 失敗（找不到指令 / `ENOENT`） |
| 79 | + |
| 80 | +最常見的 Windows 問題：`finmind-mcp` 或 `uvx` 在 PowerShell 跑得動，但 Claude Desktop 這類**圖形介面應用程式讀到的 PATH 和終端機不同**，導致 MCP server 顯示連線失敗。解法是把設定裡的 `command` 改成執行檔的**完整路徑**。先在 PowerShell 查實際位置： |
| 81 | + |
| 82 | +```powershell |
| 83 | +where.exe uvx # 方式 A |
| 84 | +where.exe finmind-mcp # 方式 B |
| 85 | +``` |
| 86 | + |
| 87 | +通常會是 `C:\Users\<你的帳號>\.local\bin\uvx.exe`（或 `finmind-mcp.exe`）。填進 JSON 時**反斜線要寫成 `\\`**，例如 Claude Desktop： |
| 88 | + |
| 89 | +```json |
| 90 | +{ |
| 91 | + "mcpServers": { |
| 92 | + "finmind": { |
| 93 | + "command": "C:\\Users\\<你的帳號>\\.local\\bin\\uvx.exe", |
| 94 | + "args": ["finmind-mcp"], |
| 95 | + "env": { |
| 96 | + "FINMIND_TOKEN": "your-token-here" |
| 97 | + } |
| 98 | + } |
| 99 | + } |
| 100 | +} |
| 101 | +``` |
| 102 | + |
| 103 | +### 改了設定卻沒有生效 |
| 104 | + |
| 105 | +Claude Desktop 關閉視窗後仍會在系統匣（工作列右下角）常駐——要在系統匣圖示上按右鍵選 **Quit / 結束** 完全關閉再重開，新設定才會載入。 |
| 106 | + |
| 107 | +### `winget` 不存在 |
| 108 | + |
| 109 | +較舊的 Windows 10 可能沒有內建 `winget`。改用方式 A 的第二行 PowerShell 安裝指令，或先從 Microsoft Store 安裝「應用程式安裝程式（App Installer）」。 |
0 commit comments