Alpaca 量化交易 API 接入 Claude MCP

先搞懂這些術語，才看得懂後面在說什麼

在開始之前，這幾個詞會反覆出現。不懂的話，後面全是天書。

Alpaca

一個提供股票量化交易的美國平台。可以用程式自動下單、查詢帳戶、讀取行情。免費帳號就能用紙上交易（模擬盤），不會動真錢。

就像一個可以用程式控制的券商帳戶，你寫程式，它幫你買賣股票。

MCP（Model Context Protocol）

Claude 的外掛插件系統。裝好 MCP Server 之後，你就可以在跟 Claude 對話時，直接叫它去操作外部工具（查股票、讀 Google Drive 等）。

就像手機 App 安裝完插件之後多了新功能，MCP 讓 Claude 多了「手」和「眼」。

MCP Server

真正跑在背景的程式，負責跟 Alpaca API 溝通。Claude 不直接碰 API，而是透過 MCP Server 這個中間人。

像餐廳的服務生，Claude 是客人點菜，MCP Server 去廚房（Alpaca）取餐。

uv / uvx

uv 是 Python 套件管理工具，比 pip 更快。uvx 是它的一個子指令，可以「臨時執行」一個 Python 工具，不需要永久安裝。Mac/Linux 系統直接有，Windows 需要先裝 uv。

uv 像工具箱，uvx 像「借來用一下就還」的模式，但 Windows 借來的東西容易出問題，所以最後我們改用永久安裝。

GCP Secret Manager

Google Cloud Platform 提供的密鑰保險箱服務。把 API Key 存在雲端，程式用 gcloud 指令來讀取，本機不留任何明文密鑰。

就像把家門鑰匙存在銀行保險箱，每次要用時去取，而不是掛在脖子上。

GBK / UTF-8 編碼

電腦存文字的「方言」。Windows 中文系統預設用 GBK（廣東話），但幾乎所有現代程式和網路都用 UTF-8（普通話）。兩邊語言不通就會報錯。

你用廣東話寫信，對方只看得懂普通話。GBK 是廣東話，UTF-8 是普通話，Windows 中文系統預設講廣東話。

整體架構是什麼樣子？

你說話給 Claude

Claude Code 對話

→

Claude 呼叫 MCP

MCP Protocol

→

wrapper.bat 啟動

讀取密鑰 + 啟動 server

→

alpaca-mcp-server

真正跑起來的程式

→

Alpaca API

查股票、下單、帳戶

為什麼 API Key 不能放在程式碼裡？

在開始安裝之前，先理解為什麼要花功夫把 API Key 存進 GCP Secret Manager，而不是直接寫在設定檔裡。

真實案例警告：明文 API Key 上傳 GitHub 的後果

網路上每天都有人不小心把含有 API Key 的設定檔 git push 到 GitHub。GitHub 有機器人會自動掃描新 commit，幾分鐘內就能被惡意爬蟲發現。

Alpaca 的 API Key 可以直接操作你的真實帳戶，下單買賣股票。一旦洩漏，後果自負。

不安全的做法

把 Key 直接寫在 .bat 或 settings.json 裡：

set APCA_API_KEY=PKxxxxx...

這個文件一旦進入 git，或者你不小心截圖分享，Key 就暴露了。

安全的做法

Key 存在 GCP Secret Manager，程式啟動時動態讀取：

本機零明文 → 截圖也沒事
git push 也沒事
分享設定檔也沒事

安裝 uv 和 alpaca-mcp-server

先把工具裝好。Windows 上需要多一個步驟，因為官方文檔預設你有 uvx，但 Windows 不一定有。

安裝 uv 工具（如果還沒裝的話）

uv 是比 pip 更快的 Python 套件管理工具，uvx 是它帶的子指令。

在命令提示字元或 PowerShell 輸入

pip install uv

裝完之後可以驗證：

uv --version
# 應該顯示類似 uv 0.x.x

安裝 alpaca-mcp-server 到穩定路徑

不要用 uvx（臨時執行模式），要用 uv tool install（永久安裝），這樣 Claude 每次啟動都能找到它。

安裝指令

uv tool install alpaca-mcp-server

安裝完成後，server 會放在這個穩定路徑（Windows）：

C:\Users\Administrator\.local\bin\alpaca-mcp-server.exe
# 如果你不是 Administrator 用戶，把 Administrator 換成你的用戶名

把 Alpaca API Key 存入 GCP Secret Manager

前往 alpaca.markets 取得你的 API Key ID 和 Secret Key。然後存入 GCP：

gcloud CLI 指令（每個 key 分開存）

# 存 API Key ID
echo -n "你的_API_KEY_ID" | gcloud secrets create alpaca-api-key \
  --data-file=- --project=你的project名

# 存 API Secret Key
echo -n "你的_API_SECRET" | gcloud secrets create alpaca-api-secret \
  --data-file=- --project=你的project名

六大卡點全紀錄

這六個問題是真實操作過程中按順序踩到的坑。每個都用「問題 → 原因 → 解決」的格式記錄，方便對照排查。

uvx 指令不存在（Windows 特有問題）

問題

Alpaca 官方文檔說「用 uvx alpaca-mcp-server 啟動」，但在 Windows 終端輸入後，報錯 'uvx' is not recognized as an internal or external command。

原因

uvx 是 uv 工具帶的子指令。官方文檔通常針對 Mac/Linux 用戶寫，那些系統可能預裝了 uv 或用不同方式安裝。Windows 預設沒有 uvx，需要先安裝 uv 才能使用。

解決

先用 pip install uv 裝好 uv 工具包，之後 uvx 指令就會出現。但注意：uvx 只是臨時執行，更好的做法見卡點 2。

MCP 顯示 Failed to connect（連線失敗）

問題

Server 裝好了，在 Claude 的 MCP 設定中加入 uvx alpaca-mcp-server，但執行 claude mcp list 仍顯示 alpaca: Failed to connect。

原因

uvx 的「臨時執行」模式每次都會重新下載相關套件，速度較慢。Claude 啟動 MCP Server 時有超時限制（health check timeout），下載沒完成就被判定連線失敗。另外，uvx 的 cache 路徑不穩定，Windows 上更容易出問題。

解決

改用 永久安裝 模式，讓 server 程式放在固定位置，啟動時不需要下載：

uv tool install alpaca-mcp-server

裝完後路徑固定在 C:\Users\你的用戶名\.local\bin\alpaca-mcp-server.exe，每次啟動快速可靠。

UnicodeDecodeError：GBK 編碼錯誤

問題

Server 啟動時報錯：
UnicodeDecodeError: 'gbk' codec can't decode byte 0xXX in position XX

原因

Windows 中文系統的預設編碼是 GBK（廣東話），但 alpaca-mcp-server 讀取 JSON 規格文件時用的是 UTF-8（普通話）。兩邊語言不通，Python 讀到 UTF-8 的特殊字符，用 GBK 解讀時就炸了。

解決

在 MCP 的環境變量設定中加入 PYTHONUTF8=1，強制 Python 全程用 UTF-8。這樣不管 Windows 系統說什麼語言，Python 都講普通話。

在 claude mcp add 或 settings.json 中加入環境變量

// settings.json 中的 mcpServers 設定
{
  "alpaca": {
    "command": "wrapper.bat",
    "env": {
      "PYTHONUTF8": "1"
    }
  }
}

Python SDK 連不上 GCP Secret Manager（DefaultCredentialsError）

問題

寫了一個 Python wrapper，用 google-cloud-secret-manager SDK 讀取 API Key，但報錯：
google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials

原因

Python SDK 透過 Application Default Credentials（ADC） 驗證身份。這需要環境中有特定的認證文件或 gcloud 登入狀態。但在 .venv 虛擬環境裡執行時，ADC 的設定可能找不到，導致驗證失敗。

解決

放棄使用 Python SDK，改用 gcloud CLI 指令 直接讀取 Secret Manager。用 subprocess 呼叫 gcloud 指令，不需要 SDK 驗證，直接繼承 gcloud 的登入狀態。

改用 gcloud CLI 讀取密鑰的 Python 寫法

import subprocess

result = subprocess.run(
    ["gcloud", "secrets", "versions", "access", "latest",
     "--secret=alpaca-api-key", "--project=你的project名"],
    capture_output=True, text=True, shell=True
)
api_key = result.stdout.strip()

subprocess 找不到 gcloud 指令（FileNotFoundError）

問題

Python wrapper 中用 subprocess 呼叫 gcloud，報錯：
FileNotFoundError: [WinError 2] The system cannot find the file specified: 'gcloud'

原因

gcloud 不在系統 PATH 中，或者 Claude Code 的子進程繼承到的 PATH 跟你手動開終端的 PATH 不同。你在終端輸入 gcloud 能用，不代表 Python 在背景呼叫時也能找到。

解決

不要依賴 PATH，直接用 gcloud 的完整絕對路徑：

用完整路徑呼叫 gcloud（Windows 預設安裝位置）

GCLOUD = r"C:\Program Files (x86)\Google\Cloud SDK\google-cloud-sdk\bin\gcloud.cmd"

result = subprocess.run(
    [GCLOUD, "secrets", "versions", "access", "latest",
     "--secret=alpaca-api-key", "--project=你的project名"],
    capture_output=True, text=True, shell=True
)

Python wrapper 手動測試沒問題，但 MCP 仍然 Failed to connect

問題

Python wrapper 寫好了，自己在終端執行完全正常，Key 也能讀出來。但 Claude 的 MCP 還是顯示 Failed to connect，無法接上。

原因

Python wrapper 最後用 os.execv() 把自己「替換成」alpaca-mcp-server 進程。這個方式在 Linux 完全沒問題，但 Windows 的 os.execv 在特定情境下有已知問題，進程替換的行為不穩定，導致 MCP 的 stdio 溝通管道出現異常。

解決

完全放棄 Python wrapper，改用 .bat 批次文件。Windows 的 bat 文件本來就是 Windows 的原生語言，執行最穩定。整個流程：讀 GCP Secret Manager → 設環境變量 → 執行 server，全部寫在 bat 裡，三步到位。

最終成功方案：wrapper.bat 一鍵搞定

兜了一大圈，最後發現最簡單的方法才是最可靠的。整個解決方案就三個文件和六個步驟。

第一步：確認 server 已安裝

終端輸入（確認 server 在正確位置）

# 如果還沒裝，先執行：
pip install uv
uv tool install alpaca-mcp-server

# 確認安裝位置
where alpaca-mcp-server
# 應顯示：C:\Users\你的用戶名\.local\bin\alpaca-mcp-server.exe

第二步：把 API Key 存入 GCP Secret Manager

前往 alpaca.markets → API Keys 取得 API Key ID 和 Secret Key（紙上交易和真實帳戶各有一組）。
建議先用紙上交易（Paper Trading）的 Key 練習，確認沒問題再換真實帳戶。

gcloud CLI 指令（在有 gcloud 的終端執行）

"C:\Program Files (x86)\Google\Cloud SDK\google-cloud-sdk\bin\gcloud.cmd" secrets create alpaca-api-key --project=你的GCP_PROJECT_ID
"C:\Program Files (x86)\Google\Cloud SDK\google-cloud-sdk\bin\gcloud.cmd" secrets create alpaca-api-secret --project=你的GCP_PROJECT_ID

# 然後各自新增版本（存入真正的值）
echo -n "PKxxxxxxxx" | "C:\Program Files (x86)\Google\Cloud SDK\google-cloud-sdk\bin\gcloud.cmd" secrets versions add alpaca-api-key --data-file=-
echo -n "xxxxxxxx" | "C:\Program Files (x86)\Google\Cloud SDK\google-cloud-sdk\bin\gcloud.cmd" secrets versions add alpaca-api-secret --data-file=-

第三步：建立 wrapper.bat 文件

新建一個文件，命名為 alpaca-mcp-wrapper.bat，存放在任意穩定位置（例如 D:\scripts\alpaca-mcp-wrapper.bat）。

alpaca-mcp-wrapper.bat 完整內容

@echo off
REM === 讀取 Alpaca API Key from GCP Secret Manager ===

REM 設定 gcloud 完整路徑（避免 PATH 問題）
SET GCLOUD="C:\Program Files (x86)\Google\Cloud SDK\google-cloud-sdk\bin\gcloud.cmd"

REM 讀取 API Key ID
FOR /F "delims=" %%i IN ('%GCLOUD% secrets versions access latest --secret=alpaca-api-key --project=你的GCP_PROJECT_ID') DO SET APCA_API_KEY_ID=%%i

REM 讀取 API Secret Key
FOR /F "delims=" %%i IN ('%GCLOUD% secrets versions access latest --secret=alpaca-api-secret --project=你的GCP_PROJECT_ID') DO SET APCA_API_SECRET_KEY=%%i

REM 強制 UTF-8（解決 Windows 中文系統 GBK 問題）
SET PYTHONUTF8=1

REM 啟動 alpaca-mcp-server
"C:\Users\Administrator\.local\bin\alpaca-mcp-server.exe"

注意：兩個地方要換成你自己的

1. 你的GCP_PROJECT_ID → 換成你 GCP 專案的實際 ID（在 GCP Console 右上角可以找到）
2. Administrator → 換成你的 Windows 用戶名（例如 Thomas）

第四步：把 wrapper.bat 加入 Claude MCP 設定

在終端執行（user scope 代表所有 project 都能用）

claude mcp add alpaca --scope user -- D:\scripts\alpaca-mcp-wrapper.bat

--scope user 是什麼意思？代表這個 MCP Server 對你電腦上所有 Claude 的 project 都有效，不需要每個 project 都重新設定一次。如果你只想在某個特定 project 用，改成 --scope project。

第五步：驗證連線成功

在終端輸入

claude mcp list

成功！應該看到這個

alpaca: Connected

這代表 Claude 已經可以透過 MCP 呼叫 Alpaca API 了。

第六步：在 Claude 中試用

開啟 Claude Code，輸入測試指令

# 詢問帳戶資訊
請幫我查看 Alpaca 帳戶餘額

# 詢問持倉
幫我列出目前的持倉部位

# 查詢行情
AAPL 現在的股價是多少？

整個踩坑旅程的時間線回顧

uvx 找不到

→ pip install uv

連線超時

→ 改用 uv tool install 永久安裝

GBK 編碼炸

→ 加環境變量 PYTHONUTF8=1

SDK 驗證失敗

→ 改用 gcloud CLI 指令

gcloud 找不到

→ 改用完整絕對路徑

os.execv 不穩

→ 放棄 Python wrapper，改用 .bat

Connected!

alpaca: Connected — 大功告成

FAQ 常見問題

Q：我沒有 GCP 帳號，API Key 可以直接放在 bat 裡嗎？

技術上可以，但強烈不建議。如果你的 bat 文件不小心上傳到 GitHub（就算是私人 repo），或者截圖分享，Key 就洩漏了。Alpaca Key 能直接操作你的帳戶下單，洩漏風險很高。GCP Secret Manager 免費額度足夠個人使用，值得花時間設定。如果真的沒有 GCP，至少把 bat 文件放在不在 git 追蹤範圍的目錄，並且在 .gitignore 中明確排除。

Q：claude mcp list 顯示 Connected，但問 Claude 帳戶資訊時說沒有工具可用？

嘗試重新啟動 Claude Code。MCP Server 連線成功不代表工具列表已載入，有時需要重啟才能讓 Claude 看到可用的工具。重啟後再試一次。

Q：Paper Trading 和真實帳戶的 Key 有什麼不同？

Alpaca 提供兩套獨立的 API Key：Paper Trading（紙上交易，模擬盤）和 Live Trading（真實帳戶）。兩套 Key 長得一樣，但操作的是不同環境。強烈建議先用 Paper Trading 的 Key 測試所有功能，確認沒有意外行為後，再換成真實帳戶的 Key。

Q：wrapper.bat 每次啟動都要等很久去讀 GCP，正常嗎？

正常，每次 Claude 啟動 MCP Server 時都會執行 bat，包括 gcloud 讀取 Secret 的步驟。通常 1-3 秒內完成。如果你覺得太慢，可以考慮把 Key 存入 Windows 的系統環境變量（但要確保是用戶環境變量而非系統環境變量，且明白這樣 Key 就保存在本機了）。

Q：我的 gcloud 裝在不同路徑，怎麼確認？

在命令提示字元輸入 where gcloud 或 where gcloud.cmd，就能看到完整安裝路徑。把 bat 文件中的路徑換成你的實際路徑即可。

Q：設定完之後，我能叫 Claude 做哪些事？

alpaca-mcp-server 支援的操作包括：查詢帳戶餘額、查看持倉部位、讀取歷史行情、下市價單和限價單、查看未完成訂單、取消訂單等。基本上你能在 Alpaca 網頁做的事，都可以叫 Claude 幫你做。

Alpaca 量化交易 API接入 Claude Code MCP

Alpaca 量化交易 API
接入 Claude Code MCP