Alpaca Trading MCP Server

Alpaca Trading MCP 服务

用于 Alpaca 交易的模型上下文协议（MCP）服务实现，可让 Anthropic Claude 等大语言模型（LLM）与 Alpaca 的交易 API 交互。 本 README 中提供的说明和命令主要面向 MacOS/Linux 用户。

演示展示了左侧的 Claude for Desktop 应用和右侧的 Alpaca 网页控制台，可用于验证操作。

简介

模型上下文协议（MCP）

模型上下文协议（MCP） 是 Anthropic 开发的一种开放协议，用于标准化应用向大模型提供上下文的方式。可以把 MCP 想象成 AI 应用的 USB-C 接口。正如 USB-C 提供了一种连接设备与各种外围设备及配件的标准方式，MCP 也提供了一种连接 AI 模型与不同数据源和工具的标准方式。

Alpaca

Alpaca 是一个现代化的经纪平台，通过方便开发者使用的 API 提供金融市场访问服务。企业可以使用 Alpaca API 构建投资应用和服务功能。此外，程序化交易者还可以开发算法来自动执行交易策略。

免责声明

重要提示：本软件按“原样”提供，不附带任何形式的保证。使用此代码即表示你知悉交易存在重大风险，且作者不对因使用本软件而产生的任何财务损失负责。用户须对使用此实现所做出的交易决策承担全部责任。在考虑使用真实资金进行实盘交易前，请务必始终使用模拟交易进行测试。

参考资料

• MCP Python SDK
• Alpaca-py SDK

功能

• 账户管理：查看账户信息和投资组合摘要
• 市场数据：获取实时行情和历史价格柱
• 交易操作：提交市价单和限价单
• 持仓跟踪：监控当前持仓和近期订单

前置要求

• uv（Python 包和项目管理器） 安装命令：

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

• [可选] Claude for Desktop（用于测试的 Claude 客户端应用）

安装

1. 克隆此仓库

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

2. [可选但推荐] 创建并激活虚拟环境：

   uv venv
   source .venv/bin/activate
   

3. 安装依赖。uv 会读取 uv.lock 文件并安装所有依赖项指定的版本

   uv sync
   

4. 在项目根目录创建 .env 文件，并填入你的 Alpaca 凭据：

   ALPACA_API_KEY=your_api_key
   ALPACA_API_SECRET=your_api_secret
   ALPACA_PAPER=TRUE
   

   注意：可在 Alpaca 开发者网页控制台获取 Alpaca API 密钥。请参阅 Alpaca 文档。

使用方法（使用 Claude for Desktop 测试 Alpaca MCP 服务）

请确保已安装 Claude for Desktop。

1. 在 Claude for Desktop 中，前往 Settings（这是菜单栏中的 Settings，而不是应用内的设置），然后前往 Developer 选项卡，点击“Edit Config”。这将定位到 claude_desktop_config.json 文件。

   或者，你也可以在 ~/Library/Application Support/Claude/claude_desktop_config.json 找到该文件（如果文件位置已更改，请参阅 MCP documentation site）。

2. 在 mcpServers 键中添加服务。

   {
       "mcpServers": {
           "alpaca": {
               "command": "/ABSOLUTE/PATH/TO/uv",
               "args": [
                   "--directory",
                   "/ABSOLUTE/PATH/TO/PARENT/FOLDER/alpaca-mcp-server",
                   "run",
                   "alpaca_mcp_server.py"
               ]
           }
       }
   }
   

   注意：请将 uv 和 alpaca-mcp-server 目录的绝对路径替换为你机器上的实际路径。提示：运行 which uv 可显示 uv 的绝对路径。

3. 如果 Claude for Desktop 已启动，请重新启动。点击锤子图标，确认可用的 MCP 工具。你可以尝试以下查询：

   • “我当前的 Alpaca 投资组合余额是多少？”
   • “以 $238 的价格买入 10 股 JPMorgan Chase 的限价单。”
   • “以市价买入 1 股 GOOGL。”
   • “以 $210 的价格卖出 1 股 AAPL 的限价单。”
   • “取消我的 AAPL 卖出限价单。” 注意：如果系统提示，请允许工具访问并运行。

可用资源

• account://info - 获取账户信息
• positions://all - 获取所有当前持仓
• market://quote/{symbol} - 获取指定股票代码的最新报价
• market://bars/{symbol} - 获取指定股票代码的历史 K 线数据（最近 7 天）
• orders://recent - 获取最近的订单（最近 7 天）

注意：实时市场数据功能（如报价和历史 K 线数据）是否可用，可能取决于你的 Alpaca 订阅级别；这些功能可能只有 Live 交易账户才能完全访问。

可用工具

• place_market_order(symbol, side, qty) - 下达市价单
• place_limit_order(symbol, side, qty, limit_price) - 下达限价单
• cancel_order(order_id) - 取消现有订单
• get_portfolio_summary() - 获取当前投资组合摘要

安全功能

• 默认使用模拟交易（ALPACA_PAPER=TRUE）
• 完善的错误处理和日志记录
• 使用 contextlib 实现平稳启动和关闭

许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

引用

如果你在研究或项目中使用了本作品，请使用以下引用：

Mardianto Hadiputro. (2025). Alpaca Trading MCP Server. GitHub. https://github.com/MardiantoS/alpaca-mcp-server