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 许可证。