Schwab MCP

🚀 嘉信理財MCP服務器

這是一個模型上下文協議（MCP）服務器，可讓Claude等AI助手通過嘉信理財官方API，安全地與嘉信理財賬戶和市場數據進行交互。

🚀 快速開始

前提條件

1. 嘉信理財開發者賬戶：在嘉信理財開發者門戶註冊。
2. Cloudflare賬戶：用於部署（使用Durable Objects需要Workers付費計劃）。
3. Node.js：版本22.x或更高。
4. Wrangler CLI：通過npm安裝（包含在開發依賴中）。

快速設置

git clone <repository-url>
cd schwab-mcp
npm install

# 首次使用時，使用Cloudflare進行身份驗證
npx wrangler login

# 創建用於存儲OAuth令牌的KV命名空間
npx wrangler kv:namespace create "OAUTH_KV"
# 記錄輸出中的ID，配置時會用到
# 設置個人配置
cp wrangler.example.jsonc wrangler.jsonc
# 編輯wrangler.jsonc：
# 1. 將YOUR_KV_NAMESPACE_ID_HERE替換為上述ID
# 2. 將名稱更改為唯一的名稱（例如，"schwab-mcp-yourname"）
# 設置密鑰
npx wrangler secret put SCHWAB_CLIENT_ID      # 您的嘉信理財應用密鑰
npx wrangler secret put SCHWAB_CLIENT_SECRET  # 您的嘉信理財應用秘鑰
npx wrangler secret put SCHWAB_REDIRECT_URI   # https://your-worker-name.workers.dev/callback
npx wrangler secret put COOKIE_ENCRYPTION_KEY # 使用openssl rand -hex 32生成
# 部署
npm run deploy

配置說明

• wrangler.example.jsonc - 模板配置（已提交）
• wrangler.jsonc - 個人配置（git忽略，從模板創建）
• .dev.vars - 本地開發密鑰（git忽略，可選）

由於wrangler.jsonc被git忽略，您可以安全地使用個人配置進行開發和測試，而不會洩露密鑰。

詳細配置

1. 創建嘉信理財應用

1. 登錄嘉信理財開發者門戶
2. 創建新應用：
   • 應用名稱：您的MCP服務器名稱
   • 回調URL：https://schwab-mcp.<your-subdomain>.workers.dev/callback
   • 應用類型：根據用例選擇個人或第三方
3. 記錄您的應用密鑰（客戶端ID）並生成應用秘鑰

2. 設置環境變量

需要設置與快速設置中相同的密鑰（見上文）。

使用GitHub Actions進行部署

對於自動部署，請添加以下GitHub倉庫密鑰：

1. CLOUDFLARE_API_TOKEN：您的Cloudflare API令牌
2. OAUTH_KV_ID：您的KV命名空間ID

當推送到main分支時，工作流會處理驗證和部署。仍需通過wrangler secret設置Cloudflare密鑰。

使用Inspector進行測試

使用MCP Inspector測試部署：

npx @modelcontextprotocol/inspector@latest

輸入https://schwab-mcp.<your-subdomain>.workers.dev/sse並連接。系統會提示您使用嘉信理財進行身份驗證。

✨ 主要特性

本MCP服務器充當AI助手和嘉信理財API之間的橋樑，提供以下功能：

• 安全的OAuth認證：實現了帶有PKCE的嘉信理財OAuth 2.0流程，確保安全認證。
• 全面的交易工具：可訪問賬戶、訂單、報價和交易記錄。
• 市場數據工具：提供實時報價、價格歷史、市場交易時間、市場變動情況和期權鏈數據。
• 賬戶隱私保護：內置賬戶標識符清理功能，保護敏感信息。
• 企業級部署：部署在Cloudflare Workers上，使用Durable Objects進行狀態管理。

📦 安裝指南

前提條件

1. 嘉信理財開發者賬戶：在嘉信理財開發者門戶註冊。
2. Cloudflare賬戶：用於部署（使用Durable Objects需要Workers付費計劃）。
3. Node.js：版本22.x或更高。
4. Wrangler CLI：通過npm安裝（包含在開發依賴中）。

快速設置

git clone <repository-url>
cd schwab-mcp
npm install

# 首次使用時，使用Cloudflare進行身份驗證
npx wrangler login

# 創建用於存儲OAuth令牌的KV命名空間
npx wrangler kv:namespace create "OAUTH_KV"
# 記錄輸出中的ID，配置時會用到
# 設置個人配置
cp wrangler.example.jsonc wrangler.jsonc
# 編輯wrangler.jsonc：
# 1. 將YOUR_KV_NAMESPACE_ID_HERE替換為上述ID
# 2. 將名稱更改為唯一的名稱（例如，"schwab-mcp-yourname"）
# 設置密鑰
npx wrangler secret put SCHWAB_CLIENT_ID      # 您的嘉信理財應用密鑰
npx wrangler secret put SCHWAB_CLIENT_SECRET  # 您的嘉信理財應用秘鑰
npx wrangler secret put SCHWAB_REDIRECT_URI   # https://your-worker-name.workers.dev/callback
npx wrangler secret put COOKIE_ENCRYPTION_KEY # 使用openssl rand -hex 32生成
# 部署
npm run deploy

💻 使用示例

基礎用法

您可以讓Claude執行以下操作：

• "顯示我的嘉信理財賬戶餘額和持倉情況"
• "獲取蘋果、谷歌和微軟的實時報價"
• "今天標準普爾500指數中漲幅最大的股票有哪些？"
• "顯示特斯拉的期權鏈和希臘值"
• "獲取我過去30天的交易記錄"
• "搜索與科技相關的交易型開放式指數基金（ETF）"
• "檢查市場是否開盤"

高級用法

Claude桌面配置

1. 使用Claude集成

1. 打開Claude桌面版設置。
2. 點擊“集成”選項卡。
3. 點擊“添加自定義集成”按鈕。
4. 輸入集成名稱“Schwab”。
5. 輸入MCP服務器URL：https://schwab-mcp.<your-subdomain>.workers.dev/sse。
6. 點擊“添加”按鈕。
7. 點擊“連接”，嘉信理財認證流程將啟動。

2. 將MCP服務器添加到Claude桌面配置中

將以下內容添加到Claude桌面配置文件中：

{
    "mcpServers": {
        "schwab": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://schwab-mcp.<your-subdomain>.workers.dev/sse"
            ]
        }
    }
}

重啟Claude桌面版。首次使用嘉信理財工具時，將打開瀏覽器窗口進行身份驗證。

示例命令

連接成功後，您可以讓Claude執行以下操作：

• "顯示我的嘉信理財賬戶餘額"
• "獲取蘋果公司的報價"
• "今天標準普爾500指數中漲幅最大的股票有哪些？"
• "顯示特斯拉的期權鏈"
• "獲取我上週的近期交易記錄"

本地開發

對於本地開發，創建一個.dev.vars文件（git會自動忽略該文件）：

SCHWAB_CLIENT_ID=your_development_app_key
SCHWAB_CLIENT_SECRET=your_development_app_secret
SCHWAB_REDIRECT_URI=http://localhost:8788/callback
COOKIE_ENCRYPTION_KEY=your_random_key_here
LOG_LEVEL=DEBUG  # 可選：啟用調試日誌

在本地運行：

npm run dev
# 服務器將在http://localhost:8788上可用

使用MCP Inspector連接到http://localhost:8788/sse進行測試。

📚 詳細文檔

功能特性

交易工具

• 賬戶管理
  • getAccounts：檢索所有賬戶信息，包括持倉和餘額。
  • getAccountNumbers：獲取賬戶標識符列表。
• 訂單管理
  • getOrder：按ID獲取訂單。
  • getOrders：按狀態、時間範圍和符號過濾獲取訂單。
  • getOrdersByAccountNumber：按賬戶號碼獲取訂單。
  • cancelOrder：取消訂單（實驗性）。
  • placeOrder：下單（實驗性）。
  • replaceOrder：替換訂單（實驗性）。
• 市場報價
  • getQuotes：獲取多個符號的實時報價。
  • getQuoteBySymbolId：獲取單個符號的詳細報價。
• 交易歷史
  • getTransactions：按日期過濾，檢索所有賬戶的交易歷史記錄。
• 用戶偏好
  • getUserPreference：檢索用戶交易偏好和設置。

市場數據工具

• 工具搜索
  • searchInstruments：通過符號搜索證券，並獲取基本面/參考數據。
• 價格歷史
  • getPriceHistory：獲取可自定義週期和頻率的歷史價格數據。
• 市場交易時間
  • getMarketHours：按日期檢查市場營業時間。
  • getMarketHoursByMarketId：獲取特定市場信息。
• 市場變動情況
  • getMovers：按指數（$SPX、$COMPX、$DJI）查找漲幅最大的股票。
• 期權鏈
  • getOptionChain：檢索完整的期權鏈數據和希臘值。
  • getOptionExpirationChain：獲取期權到期日期。

架構

技術棧

• 運行時：Cloudflare Workers，使用Durable Objects。
• 認證：通過@cloudflare/workers-oauth-provider實現帶有PKCE的OAuth 2.0認證。
• API客戶端：使用@sudowealth/schwab-api進行類型安全的嘉信理財API訪問。
• MCP框架：使用@modelcontextprotocol/sdk和workers-mcp適配器。
• 狀態管理：使用KV存儲令牌，使用Durable Objects管理會話狀態。

安全特性

1. 帶有PKCE的OAuth 2.0：安全的認證流程，防止授權碼被攔截。
2. 增強的令牌管理：
   • 集中式KV令牌存儲，支持自動遷移。
   • 自動刷新令牌（過期前5分鐘）。
   • 令牌有效期為31天，支持TTL。
3. 賬戶清理：敏感賬戶標識符會自動替換為顯示名稱。
4. 狀態安全：使用HMAC - SHA256簽名確保狀態參數的完整性。
5. Cookie加密：使用AES - 256加密客戶端批准狀態。
6. 密鑰隱藏：自動屏蔽日誌中的敏感數據。

開發

可用腳本

npm run dev          # 在端口8788上啟動開發服務器
npm run deploy       # 部署到Cloudflare Workers
npm run typecheck    # 運行TypeScript類型檢查
npm run lint         # 運行ESLint並自動修復
npm run format       # 使用Prettier格式化代碼
npm run validate     # 同時運行類型檢查和代碼檢查

調試

服務器提供了可配置級別的全面日誌記錄：

• 開發環境：終端輸出彩色日誌。
• 生產環境：Cloudflare控制檯 → Workers → 日誌。
• 日誌級別：DEBUG、INFO、WARN、ERROR（通過LOG_LEVEL環境變量設置）。 啟用調試日誌以查看詳細的OAuth流程和API交互：

# 本地開發
echo "LOG_LEVEL=DEBUG" >> .dev.vars

# 生產環境
npx wrangler secret put LOG_LEVEL --secret="DEBUG"

錯誤處理

服務器實現了強大的錯誤處理，具有特定的錯誤類型：

• 認證錯誤（401）：提示重新認證。
• 客戶端錯誤（400）：參數無效、數據缺失。
• 服務器錯誤（500）：API故障、配置問題。
• 網絡錯誤（503）：自動重試，採用退避策略。 所有錯誤都包含請求ID，便於排查嘉信理財API問題。

貢獻代碼

1. 分叉倉庫。
2. 創建功能分支（git checkout -b feature/amazing-feature）。
3. 提交更改（git commit -m 'Add amazing feature'）。
4. 推送到分支（git push origin feature/amazing-feature）。
5. 打開拉取請求。

故障排除

常見問題

1. “KV命名空間未找到”錯誤
   • 確保已創建KV命名空間並更新wrangler.jsonc。
   • 運行npx wrangler kv:namespace list進行驗證。
2. 認證失敗
   • 驗證重定向URI與嘉信理財應用設置中的完全匹配。
   • 使用npx wrangler secret list檢查所有密鑰是否正確設置。
   • 啟用調試日誌以查看詳細的OAuth流程。
3. “Durable Objects不可用”錯誤
   • 確保擁有Cloudflare Workers付費計劃。
   • 免費套餐不支持Durable Objects。
4. 令牌刷新問題
   • 服務器會在令牌過期前5分鐘自動刷新。
   • 令牌會自動從clientId遷移到schwabUserId密鑰。
   • 檢查KV命名空間中存儲的令牌：npx wrangler kv:key list --namespace-id=<your-id>

近期更新

• 增強的令牌管理：集中式KV令牌存儲可防止令牌不一致。
• 改進的安全性：HMAC - SHA256狀態驗證和自動密鑰隱藏。
• 更好的錯誤處理：結構化錯誤類型，支持嘉信理財API錯誤映射。
• 可配置的日誌記錄：調試模式可用於排查OAuth和API問題。

致謝

• 使用Cloudflare Workers構建。
• 使用Model Context Protocol。
• 由@sudowealth/schwab-api提供支持。

🔧 技術細節

技術棧

• 運行時：Cloudflare Workers，使用Durable Objects。
• 認證：通過@cloudflare/workers-oauth-provider實現帶有PKCE的OAuth 2.0認證。
• API客戶端：使用@sudowealth/schwab-api進行類型安全的嘉信理財API訪問。
• MCP框架：使用@modelcontextprotocol/sdk和workers-mcp適配器。
• 狀態管理：使用KV存儲令牌，使用Durable Objects管理會話狀態。

安全特性

1. 帶有PKCE的OAuth 2.0：安全的認證流程，通過PKCE防止授權碼被攔截，確保認證的安全性。
2. 增強的令牌管理：
   • 集中式KV令牌存儲，支持自動遷移，方便管理不同環境下的令牌。
   • 自動刷新令牌（過期前5分鐘），保證令牌的有效性，減少手動干預。
   • 令牌有效期為31天，支持TTL，有效控制令牌的生命週期。
3. 賬戶清理：敏感賬戶標識符會自動替換為顯示名稱，保護用戶的賬戶隱私。
4. 狀態安全：使用HMAC - SHA256簽名確保狀態參數的完整性，防止數據被篡改。
5. Cookie加密：使用AES - 256加密客戶端批准狀態，保證用戶交互過程中的數據安全。
6. 密鑰隱藏：自動屏蔽日誌中的敏感數據，避免敏感信息洩露。

📄 許可證

本項目採用MIT許可證。