Alpaca MCP Server

🚀 Alpaca MCP 服務器

Alpaca MCP 服務器是一個用於 Alpaca 交易 API 的模型上下文協議（MCP）服務器實現。它使 Claude Desktop、Cursor 或 VScode 上的大語言模型（LLM）能夠使用自然語言（英語）與 Alpaca 的交易基礎設施進行交互。該服務器支持股票交易、期權交易、投資組合管理、觀察列表處理以及實時市場數據訪問。

🚀 快速開始

本服務器允許大語言模型與 Alpaca 的交易基礎設施進行自然語言交互。若要開始使用，請確保滿足以下前提條件並完成安裝步驟。

✨ 主要特性

• 市場數據
  • 股票的實時報價、交易和價格柱
  • 歷史價格數據和交易歷史
  • 期權合約報價和希臘值（通過快照）
• 賬戶管理
  • 查看餘額、購買力和賬戶狀態
  • 檢查所有持倉和已平倉頭寸
• 頭寸管理
  • 獲取單個持倉的詳細信息
  • 按股數或百分比清算全部或部分頭寸
• 訂單管理
  • 下達股票和期權訂單（市價或限價）
  • 單獨或批量取消訂單
  • 獲取完整的訂單歷史記錄
• 期權交易
  • 按到期日或行權價搜索和查看期權合約
  • 下達多腿期權策略訂單
  • 獲取合約的最新報價和希臘值
• 市場狀態和企業行動
  • 檢查市場是否開放
  • 獲取市場日曆和交易時段
  • 查看即將發佈的企業公告（收益、拆股、股息）
• 觀察列表管理
  • 創建、更新和查看個人觀察列表
  • 管理多個觀察列表以跟蹤資產
• 資產搜索
  • 查詢股票和其他 Alpaca 支持的資產的詳細信息

📦 安裝指南

前提條件

• Python 3.10 及以上版本
• GitHub 賬戶
• Alpaca API 密鑰（具備模擬或實盤交易權限）
• Claude for Desktop 或其他兼容的 MCP 客戶端

安裝步驟

1. 克隆倉庫並進入倉庫目錄：

   git clone https://github.com/alpacahq/alpaca-mcp-server.git
   cd alpaca-mcp-server
   

2. 創建並激活虛擬環境：

   python3 -m venv venv
   source venv/bin/activate
   

   注意：虛擬環境將使用創建它時所用的 Python 版本。若使用 Python 3.10 或更高版本運行該命令，虛擬環境也將使用 Python 3.10 及以上版本。激活虛擬環境後，可運行 python3 --version 命令確認版本。

3. 安裝所需的包：

   pip install -r requirements.txt
   

📚 詳細文檔

項目結構

克隆倉庫並激活虛擬環境後，目錄結構應如下所示：

alpaca-mcp-server/          ← 這是工作區文件夾（即項目根目錄）
├── alpaca_mcp_server.py    ← 腳本直接位於工作區根目錄
├── .vscode/                ← VS Code 設置（適用於 VS Code 用戶）
│   └── mcp.json
├── venv/                   ← 虛擬環境文件夾
│   └── bin/python
├── .env.example            ← 環境模板（用於創建 .env 文件）
├── .gitignore              
├── Dockerfile              ← Docker 配置（用於 Docker 使用）
├── .dockerignore           ← Docker 忽略文件（用於 Docker 使用）
├── requirements.txt           
└── README.md

創建並編輯項目目錄中的 .env 文件以存儲憑證

ALPACA_API_KEY = "your_alpaca_api_key"
ALPACA_SECRET_KEY = "your_alpaca_secret_key"
PAPER = True
TRADE_API_URL = None
TRDE_API_WSS = None
DATA_API_URL = None
STREAM_DATA_WSS = None

Claude Desktop 使用方法

官方 Claude Desktop 設置文檔可在此處查看：https://modelcontextprotocol.io/quickstart/user

啟動 MCP 服務器

在項目根目錄下打開終端並運行以下命令：

python alpaca_mcp_server.py # 或者 `python -m alpaca_mcp_server`

Claude for Desktop 配置

1. 打開 Claude Desktop
2. 導航至：設置 → 開發者 → 編輯配置
3. 更新 claude_desktop_config.json：

注意： 將 <project_root> 替換為克隆的 alpaca-mcp-server 目錄的路徑。這應指向在終端中使用 python3 -m venv venv 創建的虛擬環境內的 Python 可執行文件。

{
  "mcpServers": {
    "alpaca": {
      "command": "<project_root>/venv/bin/python",
      "args": [
        "/path/to/alpaca-mcp-server/alpaca_mcp_server.py"
      ],
      "env": {
        "ALPACA_API_KEY": "your_alpaca_api_key_for_paper_account",
        "ALPACA_SECRET_KEY": "your_alpaca_secret_key_for_paper_account"
      }
    }
  }
}

VS Code 使用方法

VS Code 通過 GitHub Copilot 的代理模式支持 MCP 服務器。 官方 VS Code 設置文檔可在此處查看：https://code.visualstudio.com/docs/copilot/chat/mcp-servers

前提條件

• 安裝了 GitHub Copilot 擴展並擁有有效訂閱的 VS Code
• Python 3.10 及以上版本和已設置的虛擬環境（遵循上述安裝步驟）
• 在 VS Code 中啟用 MCP 支持（見下文）

1. 在 VS Code 中啟用 MCP 支持

1. 打開 VS Code 設置（Ctrl/Cmd + ,）
2. 搜索 "chat.mcp.enabled" 並勾選以啟用 MCP 支持
3. 搜索 "github.copilot.chat.experimental.mcp" 並勾選以使用指令文件

2. 配置 MCP 服務器

建議：使用特定於工作區的配置（.vscode/mcp.json）而非全局用戶配置。這允許不同項目使用不同的 API 密鑰（多個模擬賬戶或實盤交易），並使交易工具與其他開發工作隔離。

特定於工作區的設置：

1. 在項目根目錄下創建 .vscode/mcp.json。
2. 手動將 Alpaca MCP 服務器配置添加到 mcp.json 文件中：

   {
     "alpaca": {
       "type": "stdio",
       "command": "${workspaceFolder}/venv/bin/python",
       "args": ["${workspaceFolder}/alpaca_mcp_server.py"],
       "env": {
         "ALPACA_API_KEY": "your_alpaca_api_key",
         "ALPACA_SECRET_KEY": "your_alpaca_secret_key"
       }
     }
   }
   

   注意：對於 Windows 用戶，將 "command" 參數替換為 "${workspaceFolder}\venv\Scripts\python.exe"

全局用戶設置： 若要為所有工作區配置 MCP 服務器，可將服務器配置添加到用戶設置文件 settings.json 中。這允許在多個項目中重用相同的服務器配置。 在 VS Code 用戶設置（settings.json）的 mcp 字段中指定服務器，以在所有工作區中啟用 MCP 服務器。

{
  "mcp": {
    "servers": {
      "alpaca": {
        "type": "stdio",
        "command": "${workspaceFolder}/venv/bin/python",
        "args": ["${workspaceFolder}/alpaca_mcp_server.py"],
        "env": {
          "ALPACA_API_KEY": "your_alpaca_api_key",
          "ALPACA_SECRET_KEY": "your_alpaca_secret_key"
        }
      }
    }
  }
}

Docker 使用方法

前提條件： 系統中必須安裝 Docker。

運行最新發布的鏡像（推薦大多數用戶使用）

docker run -it --rm \
  -e ALPACA_API_KEY=your_alpaca_api_key \
  -e ALPACA_SECRET_KEY=your_alpaca_secret_key \
  ghcr.io/chand1012/alpaca-mcp-server:latest

此命令將拉取並運行服務器的最新發布版本。將 your_alpaca_api_key 和 your_alpaca_secret_key 替換為實際的密鑰。若服務器暴露了端口（例如 8080），可在命令中添加 -p 8080:8080。

本地構建並運行（用於開發或自定義更改）

docker build -t alpaca-mcp-server .
docker run -it --rm \
  -e ALPACA_API_KEY=your_alpaca_api_key \
  -e ALPACA_SECRET_KEY=your_alpaca_secret_key \
  alpaca-mcp-server

若要運行服務器的修改版本或開發版本，請使用此方法。

與 Claude Desktop 配合使用

{
  "mcpServers": {
    "alpaca": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "ALPACA_API_KEY",
        "-e", "ALPACA_SECRET_KEY",
        "ghcr.io/chand1012/alpaca-mcp-server:latest"
      ],
      "env": {
        "ALPACA_API_KEY": "your_alpaca_api_key",
        "ALPACA_SECRET_KEY": "your_alpaca_secret_key"
      }
    }
  }
}

環境變量可以通過 -e 標誌或 "env" 對象設置，但不能同時使用兩者。對於 Claude Desktop，請使用 "env" 對象。

安全注意事項： 切勿共享 API 密鑰或將其提交到公共倉庫。在共享或生產環境中傳遞機密信息作為環境變量時要格外謹慎。

更多高級 Docker 使用方法： 請參閱 官方 Docker 文檔。

實盤交易的 API 密鑰配置

此 MCP 服務器默認連接到 Alpaca 的模擬交易 API 以進行安全測試。 若要啟用使用真實資金的實盤交易，請更新以下配置文件：

🔐 在兩個位置設置 API 憑證

1. 項目目錄中的 .env 文件

   ALPACA_API_KEY = "your_alpaca_api_key_for_live_account"
   ALPACA_SECRET_KEY = "your_alpaca_secret_key_for_live_account"
   PAPER = False
   TRADE_API_URL = None
   TRDE_API_WSS = None
   DATA_API_URL = None
   STREAM_DATA_WSS = None
   

2. Claude for Desktop 配置 在 claude_desktop_config.json 中，將實盤賬戶的密鑰作為環境變量提供：

   {
     "mcpServers": {
       "alpaca": {
         "command": "<project_root>/venv/bin/python",
         "args": [
           "/path/to/alpaca_mcp_server.py"
         ],
         "env": {
           "ALPACA_API_KEY": "your_alpaca_api_key_for_live_account",
           "ALPACA_SECRET_KEY": "your_alpaca_secret_key_for_live_account"
         }
       }
     }
   }
   

💻 使用示例

可用工具

賬戶與頭寸

• get_account_info() – 查看餘額、保證金和賬戶狀態
• get_positions() – 列出所有持倉資產
• get_open_position(symbol) – 獲取特定頭寸的詳細信息
• close_position(symbol, qty|percentage) – 平倉部分或全部頭寸
• close_all_positions(cancel_orders) – 清算整個投資組合

股票市場數據

• get_stock_quote(symbol) – 實時買賣報價
• get_stock_bars(symbol, start_date, end_date) – 歷史 OHLCV 價格柱
• get_stock_latest_trade(symbol) – 最新市場交易價格
• get_stock_latest_bar(symbol) – 最近的 OHLC 價格柱
• get_stock_trades(symbol, start_time, end_time) – 交易級歷史記錄

訂單

• get_orders(status, limit) – 獲取所有或過濾後的訂單
• place_stock_order(symbol, side, quantity, order_type="market", limit_price=None, stop_price=None, trail_price=None, trail_percent=None, time_in_force="day", extended_hours=False, client_order_id=None) – 下達任何類型的股票訂單（市價、限價、止損、止損限價、跟蹤止損）
• cancel_order_by_id(order_id) – 取消特定訂單
• cancel_all_orders() – 取消所有未完成訂單

期權

• get_option_contracts(underlying_symbol, expiration_date) – 獲取期權合約
• get_option_latest_quote(option_symbol) – 合約的最新買賣報價
• get_option_snapshot(symbol_or_symbols) – 獲取希臘值和標的資產信息
• place_option_market_order(legs, order_class, quantity) – 執行期權策略

市場信息和企業行動

• get_market_clock() – 市場開閉時間表
• get_market_calendar(start, end) – 節假日和交易日
• get_corporate_announcements(...) – 收益、股息、拆股公告

觀察列表

• create_watchlist(name, symbols) – 創建新的觀察列表
• update_watchlist(id, name, symbols) – 修改現有觀察列表
• get_watchlists() – 獲取所有保存的觀察列表

資產

• get_asset_info(symbol) – 搜索資產元數據
• get_all_assets(status) – 列出所有可交易工具

自然語言查詢示例

以下是 50 個真實的查詢示例，涵蓋了從交易到企業數據再到期權策略的各個方面。

基本交易

1. 我當前的賬戶餘額和購買力是多少？
2. 顯示我當前的持倉。
3. 以市價買入 10 股蘋果（AAPL）股票。
4. 以 300 美元的限價賣出 5 股特斯拉（TSLA）股票。
5. 取消所有未完成的股票訂單。
6. 取消 ID 為 abc123 的訂單。
7. 清算我在谷歌（GOOGL）的全部頭寸。
8. 平倉我在英偉達（NVDA）10% 的頭寸。
9. 我目前持有多少股亞馬遜（AMZN）股票？
10. 以 450 美元的限價買入 100 股微軟（MSFT）股票。
11. 以市價賣出 25 股 Meta（META）股票。

期權交易

12. 顯示蘋果（AAPL）下個月到期的可用期權合約。
13. 獲取 AAPL250613C00200000 期權合約的最新報價。
14. 獲取 SPY250627P00400000 期權合約的快照信息。
15. 清算我下週到期的 2 份納斯達克 100 指數基金（QQQ）看漲期權頭寸。
16. 以市價買入一份蘋果（AAPL）下週五到期的看漲期權。
17. TSLA250620P00500000 期權合約的希臘值是多少？
18. 查找特斯拉（TSLA）行權價在當前市場價格 5% 範圍內的所有期權合約。
19. 獲取 6 月到期的所有標普 500 指數基金（SPY）看漲期權合約。
20. 使用蘋果（AAPL）6 月 6 日的期權構建牛市看漲價差策略：一份行權價為 190.00，另一份行權價為 200.00。

市場信息

21. 美國股市目前是否開放？
22. 今天的市場開盤和收盤時間是什麼時候？
23. 顯示下週的市場日曆。
24. 本月主要科技股是否有企業公告？
25. 標普 500 指數基金（SPY）的下一次股息公告是什麼時候？
26. 列出明天的收益公告。

歷史和實時數據

27. 顯示蘋果（AAPL）過去 5 個交易日的每日價格歷史。
28. 特斯拉（TSLA）昨天的收盤價是多少？
29. 獲取谷歌（GOOG）的最新價格柱。
30. 英偉達（NVDA）的最新交易價格是多少？
31. 顯示微軟（MSFT）的最新報價。
32. 獲取 AMD 過去 100 筆交易記錄。
33. 顯示亞馬遜（AMZN）上週二至上週五行的日內價格柱。

訂單

34. 顯示我本週所有未完成和已成交的訂單。
35. 我有哪些關於蘋果（AAPL）的訂單？
36. 列出我過去 3 天內下達的所有限價訂單。
37. 按狀態過濾所有訂單：已成交。
38. 獲取我昨天的訂單歷史記錄。

觀察列表

39. 創建一個名為 "科技股" 的新觀察列表，包含蘋果（AAPL）、微軟（MSFT）和英偉達（NVDA）。
40. 更新我的 "科技股" 觀察列表，使其包含特斯拉（TSLA）和亞馬遜（AMZN）。
41. 我的 "股息精選" 觀察列表中有哪些股票？
42. 從我的 "成長型投資組合" 觀察列表中移除 Meta（META）。
43. 列出我所有現有的觀察列表。

資產信息

44. 搜索資產 "AAPL" 的詳細信息。
45. 列出所有可交易的美國大盤股。
46. 顯示按交易量排名前 5 的可交易加密資產。
47. 過濾所有狀態為 "活躍" 的資產。
48. 顯示股票代碼為 "GOOGL" 的股票詳細信息。

綜合場景

49. 獲取今天的市場時鐘信息，並在以 340 美元的限價買入特斯拉（TSLA）股票之前顯示我的購買力。
50. 使用標普 500 指數基金（SPY）7 月 3 日的期權構建牛市看漲價差策略：買入一份高於當前市場價格 5% 的期權，賣出一份低於當前市場價格 3% 的期權。

輸出示例

MCP 服務器為各種交易查詢提供詳細、格式良好的響應。以下是一些示例：

期權希臘值分析

查詢："TSLA250620P00500000 期權合約的希臘值是多少？"

響應： 期權詳情：

• 當前買賣報價：$142.62 / $143.89
• 最後成交價：$138.85
• 隱含波動率：92.54%

希臘值：

• Delta：-0.8968（極度看跌）
• Gamma：0.0021（低變化率）
• Theta：-0.2658（時間衰減：$26.58/天）
• Vega：0.1654（波動率敏感度）
• Rho：-0.3060（利率敏感度）

關鍵洞察：

• 高隱含波動率（92.54%）
• 深度實值期權（Delta：-0.90）
• 顯著的時間衰減（$27/天）

多腿期權訂單

查詢："使用蘋果（AAPL）6 月 6 日的期權構建牛市看漲價差策略：一份行權價為 190.00，另一份行權價為 200.00。"

響應： 訂單詳情：

• 訂單 ID：fc1c04b1-8afa-4b2d-aab1-49613bbed7cb
• 訂單類型：多腿（MLEG）
• 狀態：待處理
• 數量：1 個價差組合

價差組合腿：

1. 多頭腿（買入）：
   • AAPL250606C00190000（行權價 $190.00）
   • 狀態：待處理
2. 空頭腿（賣出）：
   • AAPL250606C00200000（行權價 $200.00）
   • 狀態：待處理

策略總結：

• 最大利潤：每個價差組合 $10.00
• 最大損失：支付的淨借方
• 盈虧平衡點：$190 + 支付的淨借方

這些示例展示了服務器能夠提供：

• 詳細的市場數據分析
• 全面的訂單執行細節
• 清晰的策略解釋
• 格式良好、易於閱讀的響應

服務器在所有支持的查詢中都保持這種詳細程度和格式，便於用戶理解和根據提供的信息採取行動。

⚠️ 重要提示

⚠️ 重要提示

此服務器可以進行真實交易並訪問您的投資組合。請將您的 API 密鑰視為敏感憑證。仔細審查大語言模型提出的所有操作，特別是對於複雜的期權策略或多腿交易。

📄 許可證

本項目採用 MIT 許可證。