使用说明

羊驼MCP服务器

这是Alpaca的Trading API的模型上下文协议（MCP）服务器实现。它使Claude Desktop、Cursor或VScode上的大型语言模型（LLM）能够使用自然语言（英语）与Alpaca的交易基础设施进行交互。此服务器支持股票交易、期权交易、投资组合管理、观察名单处理和实时市场数据访问。

特性

市场数据
- 股票的实时报价、交易和价格条
- 历史价格数据和交易历史
- 期权合约报价和希腊语（通过快照）
账户管理
- 查看余额、购买力和账户状态
- 检查所有打开和关闭位置
职位管理
- 获取个人持股的详细信息
- 按股份数量或百分比清算全部或部分头寸
订单管理
- 下股票和期权订单（市价或限价）
- 单独或批量取消订单
- 检索完整的订单历史记录
期权交易
- 按到期或执行价格搜索和查看期权合约
- 制定多腿期权策略
- 获取合同的最新报价和希腊语
市场状况和公司行为
- 检查市场是否开放
- 获取市场日历和交易时段
- 查看即将发布的公司公告（收益、拆分、股息）
观察名单管理
- 创建、更新和查看个人监视列表
- 管理多个监视列表以跟踪资产
资产搜索
- 查询股票和其他羊驼支持资产的详细信息

0.先决条件

python
GitHub账号
Alpaca API密钥（具有纸质或实时交易访问权限）
Claude for Desktop或其他兼容的MCP客户端

1.安装

克隆存储库并导航到以下目录：

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

创建并激活虚拟环境：
```
python3 -m venv venv
source venv/bin/activate
```
注：虚拟环境将使用用于创建它的Python版本。如果您使用Python 3.10或更高版本运行该命令，您的虚拟环境也将使用Python 3.10+。如果要确认版本，可以运行 python3 --version 在激活虚拟环境之后。
安装所需的软件包：
```
pip install -r requirements.txt
```

项目结构

克隆并激活虚拟环境后，您的目录结构应该如下所示：

alpaca-mcp-server/          ← This is the workspace folder (= project root)
├── alpaca_mcp_server.py    ← Script is directly in workspace root
├── .github/                ← VS Code settings (for VS Code users)
│ ├── core/                 ← Core utility modules
│ └── workflows/            ← GitHub Actions workflows
├── .vscode/                ← VS Code settings (for VS Code users)
│   └── mcp.json
├── venv/                   ← Virtual environment folder
│   └── bin/python
├── .env.example            ← Environment template (use this to create `.env` file)
├── .gitignore              
├── Dockerfile              ← Docker configuration (for Docker use)
├── .dockerignore           ← Docker ignore (for Docker use)
├── requirements.txt           
└── README.md

2.在项目目录中为您的凭据创建和编辑.env文件

通过运行以下命令复制项目根目录中的示例环境文件：
```
cp .env.example .env
```

替换中的凭据（例如API密钥 .env 文件：

ALPACA_API_KEY = "your_alpaca_api_key_for_paper_account"
ALPACA_SECRET_KEY = "your_alpaca_secret_key_for_paper_account"
ALPACA_PAPER_TRADE = True
TRADE_API_URL = None
TRDE_API_WSS = None
DATA_API_URL = None
STREAM_DATA_WSS = None

Claude桌面使用情况

要在Claude Desktop上使用Alpaca MCP服务器，请按照以下步骤操作。Claude Desktop的官方设置文档可在此处获取：https://modelcontextprotocol.io/quickstart/user

启动MCP服务器

在项目根目录中打开终端并运行以下命令（或使用 python -m alpaca_mcp_server):

python alpaca_mcp_server.py

Claude用于桌面配置

打开克劳德桌面
导航到： Settings → Developer → Edit Config
更新您的 claude_desktop_config.json:

注：
将<project_root>替换为克隆羊驼mcp服务器目录的路径。这应该指向您使用创建的虚拟环境中的Python可执行文件 python3 -m venv venv 在终端。

{
  "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"
      }
    }
  }
}

Claude代码使用

要使用带有Claude Code的Alpaca MCP服务器，请按照以下步骤操作。

这 claude mcp add command 是的一部分克劳德代码。如果您安装了Claude MCP CLI工具（例如通过 npm install -g @anthropic-ai/claude-code)，您可以使用此命令将服务器添加到Claude Code中：

claude mcp add alpaca \
  /path/to/your/alpaca-mcp-server/venv/bin/python \
  /path/to/your/alpaca-mcp-server/alpaca_mcp_server.py \
  -e ALPACA_API_KEY=your_api_key \
  -e ALPACA_SECRET_KEY=your_secret_key

注：将路径替换为实际的项目目录路径。此命令会自动将MCP服务器配置添加到Claude代码中，而无需手动编辑JSON。

Claude MCP CLI工具需要单独安装。查看以下官方页面了解可用性和安装说明

光标使用

要使用带有Cursor的Alpaca MCP服务器，请按照以下步骤操作。Cursor MCP的官方设置文档可在此处获取：https://docs.cursor.com/context/mcp

先决条件

Cursor IDE安装时启用了Claude AI
Python和虚拟环境设置（按照上面的安装步骤）

配置MCP服务器

方法1：使用JSON配置

创建或编辑 ~/.cursor/mcp.json （macOS/Linux）或 %USERPROFILE%\.cursor\mcp.json （Windows）：

{
  "mcpServers": {
    "alpaca": {
      "command": "/path/to/your/alpaca-mcp-server/venv/bin/python",
      "args": [
        "/path/to/your/alpaca-mcp-server/alpaca_mcp_server.py"
      ],
      "env": {
        "ALPACA_API_KEY": "your_alpaca_api_key",
        "ALPACA_SECRET_KEY": "your_alpaca_secret_key"
      }
    }
  }
}

方法2：使用光标设置UI

打开光标设置→ 工具和集成 → MCP工具
点击 “+新MCP服务器”
使用与上述JSON方法相同的详细信息进行配置

注：将路径替换为实际的项目目录路径和API凭据。

VS代码使用

要使用带有VS代码的Alpaca MCP服务器，请按照以下步骤操作。

VS Code通过GitHub Copilot的代理模式支持MCP服务器。官方VS Code设置文档可在此处获得：https://code.visualstudio.com/docs/copilot/chat/mcp-servers

先决条件

VS Code已安装GitHub Copilot扩展并激活订阅
Python和虚拟环境设置（按照上面的安装步骤）
VS代码中启用了MCP支持（见下文）

1.在VS代码中启用MCP支持

打开VS代码设置（Ctrl/Cmd+，）
搜索“chat.mcp.enabled”以选中启用mcp支持的复选框
搜索“github.copilot.chat.experimental.mcp”以选中使用指令文件的复选框

2.配置MCP服务器

建议： 使用 特定工作空间 配置(.vscode/mcp.json)而不是用户范围的配置。这允许不同的项目使用不同的API密钥（多个纸质账户或实时交易），并将交易工具与其他开发工作隔离开来。

对于特定于工作区的设置：

创建 .vscode/mcp.json 在您的项目根目录中。

手动将Alpaca MCP服务器配置添加到MCP.json文件中：

对于Linux/macOS：

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

对于Windows：

{
  "mcp": {
    "servers": {
      "alpaca": {
        "type": "stdio", 
        "command": "cmd",
        "args": ["/c", "cd /d ${workspaceFolder} && .\\venv\\Scripts\\activate && python alpaca_mcp_server.py"],
        "env": {
          "ALPACA_API_KEY": "your_alpaca_api_key",
          "ALPACA_SECRET_KEY": "your_alpaca_secret_key"
        }
      }
    }
  }
}

注：替换 ${workspaceFolder} 根据您的实际项目路径。例如：

Linux/macOS： /Users/username/Documents/alpaca-mcp-server
窗户： C:\\Users\\username\\Documents\\alpaca-mcp-server

对于用户范围的设置：

要为所有工作区配置MCP服务器，您可以将服务器配置添加到user-settings.json文件中。这允许您在多个项目中重用相同的服务器配置。在中指定服务器 mcp VS代码用户设置(settings.json)以在所有工作区中启用MCP服务器。

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

PyCharm 使用

要将Alpaca MCP服务器与PyCharm一起使用，请按照以下步骤操作。在PyCharm中配置MCP服务器的官方设置指南可在此处获得：https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html

PyCharm通过其集成的MCP客户端功能支持MCP服务器。此配置可确保正确的日志记录行为，并防止常见的启动问题。

打开PyCharm设置
- 首选 File → Settings
- 引导到 Tools → Model Context Protocol (MCP) （或类似位置，具体取决于PyCharm版本）
添加新的MCP服务器
- 点击 Add 或 + 创建新的服务器配置。您还可以通过单击相应的按钮从Claude导入设置。
- 名字：为此服务器配置输入您喜欢的任何名称（例如Alpaca MCP）。
- 命令：“/path/to/your/alpaca mcp服务器/vev/bin/python”
- 参数：“alpaca_mcp_server.py”
- 工作目录：“/path/to/your/alpaca mcp服务器”

设置环境变量 在“环境变量”参数中添加以下环境变量：

ALPACA_API_KEY="your_alpaca_api_key"
ALPACA_SECRET_KEY="your_alpaca_secret_key"
MCP_CLIENT=pycharm

Docker使用

要将Alpaca MCP Server与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凭据：

更新项目目录中的环境文件

在中提供您的真实帐户密钥作为环境变量 .env 文件：

ALPACA_API_KEY = "your_alpaca_api_key_for_live_account"
ALPACA_SECRET_KEY = "your_alpaca_secret_key_for_live_account"
ALPACA_PAPER_TRADE = False
TRADE_API_URL = None
TRADE_API_WSS = None
DATA_API_URL = None
STREAM_DATA_WSS = None

更新配置文件

例如，在使用Claude 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, days=5, timeframe="1Day", limit=None, start=None, end=None) –具有灵活时间框架（1分钟、5分钟、1小时、1天等）的OHLCV历史柱状图
get_stock_latest_trade(symbol, feed=None, currency=None) –最新市场交易价格
get_stock_latest_bar(symbol, feed=None, currency=None) –最新OHLC酒吧
get_stock_snapshot(symbol_or_symbols, feed=None, currency=None) –综合快照，包括最新报价、交易、分钟柱状图、每日柱状图和之前的每日柱状图
get_stock_trades(symbol, days=5, limit=None, sort=Sort.ASC, feed=None, currency=None, asof=None) –交易水平历史

订单

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=None, expiration_month=None, expiration_year=None, expiration_week_start=None, strike_price_gte=None, strike_price_lte=None, type=None, status=None, root_symbol=None, limit=None) –获取具有全面过滤选项的合约
get_option_latest_quote(option_symbol) –最新的合同买卖
get_option_snapshot(symbol_or_symbols) –获得希腊人和底层
place_option_market_order(legs, order_class=None, quantity=1, time_in_force=TimeInForce.DAY, extended_hours=False) –执行期权策略

市场信息和公司行动

get_market_clock() –市场开盘/收盘时间表
get_market_calendar(start, end) –节假日和交易日
get_corporate_announcements(...) –收益、股息、拆分

收看列表

create_watchlist(name, symbols) –创建新列表
update_watchlist(watchlist_id, name=None, symbols=None) –修改现有列表
get_watchlists() –检索所有已保存的监视列表

资产

get_asset_info(symbol) –搜索资产元数据
get_all_assets(status=None, asset_class=None, exchange=None, attributes=None) –列出所有具有过滤选项的可交易工具

自然语言查询示例

请参阅下面的“示例查询”部分，了解50个真实示例，涵盖从交易到公司数据再到期权策略的所有内容。

基本交易

我的经常账户余额和对羊驼的购买力是多少？
显示我在Alpaca账户中的当前头寸。
以市场价格购买5股AAPL股票。
以300美元的限价出售5股TSLA股票。
取消所有未结库存订单。
取消ID为abc123的订单。
清算我在GOOGL的全部职位。
关闭我在NVDA 10%的职位。
我目前持有多少AMZN股份？
下达限价订单，以450美元的价格购买100股微软股票。
下市价单卖出25股META。

期权交易

显示下个月到期的AAPL可用期权合约。
获取AAPL250613C00200000选项的最新报价。
检索SPY250627P00400000选项的选项快照。
清算我在下周到期的两份QQQ通话合同中的头寸。
下单购买下周五到期的AAPL看涨期权。
TSLA250620P00500000选项的希腊选项是什么？
找到执行价格在当前市场价格5%以内的TSLA期权合约。
获得2025年6月16日当周到期的SPY看涨期权，价格在市场价格的10%以内。
使用AAPL 6月6日期权设置看涨看涨价差：一个是190.00次方，另一个是200.00次方。

市场信息

美国股市目前是否开放？
今天市场的开盘和收盘时间是什么时候？
给我看看下周的市场日历。
本月有大型科技股的公司公告吗？
SPY的下一个股息公告是什么？

历史和实时数据

显示AAPL过去5个交易日的每日价格历史。
TSLA昨天的收盘价是多少？
获取GOOGL的最新酒吧。
NVDA的最新交易价格是多少？
给我看看微软的最新报价。
检索AMD的最近100笔交易。
显示AMZN过去2小时的1分钟柱状图。
获取TSLA从上周二到上周五的5分钟日内酒吧。
获取AAPL的全面股票快照，在一个视图中显示最新报价、交易、分钟柱状图、每日柱状图和之前的每日柱状图。
比较TSLA、NVDA和MSFT的市场快照，分析其当前的买卖价差、最新交易价格和每日表现。

订单

向我展示本周所有未完成和已完成的订单。
我对AAPL有什么订单？
列出我在过去3天内下达的所有限价订单。
按状态筛选所有订单：已完成。
把昨天的订单历史记录给我。

收看列表

与AAPL、MSFT和NVDA一起创建一个名为“科技股”的新观察名单。
更新我的“科技股”观察名单，以包括TSLA和AMZN。
我的“股息选择”观察名单中有哪些股票？
从我的“成长投资组合”观察名单中删除META。
列出我现有的所有观察名单。

资产信息

搜索有关资产“AAPL”的详细信息。
按交易量显示前5大可交易加密资产。
筛选状态为“活跃”的科技股资产。

组合场景

在以340美元的价格为TSLA下达限价买入订单之前，请获取今天的市场时钟，并向我展示我的购买力。
使用SPY 7月3日期权进行看涨期权价差：在当前SPY价格上方5%买入一个，在下方3%卖出一个。

输出示例

MCP服务器为各种交易查询提供详细、格式良好的响应。以下是一些示例：

期权希腊分析

问：“TSLA250620P00500000的希腊选项是什么？”

答复：选项详细信息：

当前买入价/卖出价：142.62美元/143.89美元
最后一笔交易：138.85美元
隐含波动率：92.54%

希腊人：

德尔塔：-0.8968（非常熊）
伽玛：0.0021（低变化率）
Theta：-0.2658（时间衰减：26.58美元/天）
Vega:0.1654（波动敏感性）
Rho:-0.3060（利率敏感性）

关键见解：

高隐含波动率（92.54%）
深入金钱（德尔塔：-0.90）
显著时间衰减（27美元/天）

多腿期权订单

查询：“使用AAPL 6月6日期权设置看涨看涨价差：一个有190.00的罢工，另一个有200.00的罢工。”

答复：订单详细信息：

订单编号：fc1c04b1-8afa-4b2d-aab1-49613bbed7cb
订单类别：多腿（MLEG）
状态：待定新
数量：1份

伸展腿：

长腿（买）：
- AAPL250606C00190000（190.00美元罢工）
- 状态：待定新
短腿（出售）：
- 25060600澳元（200美元罢工）
- 状态：待定新

战略总结：

最大利润：每次点差10.00美元
最大损失：已支付的净借记
盈亏平衡：支付190美元+净借记

这些示例展示了服务器提供以下功能的能力：

详细的市场数据分析
全面的订单执行详情
清晰的战略解释
格式良好、易于阅读的回复

服务器在所有支持的查询中保持这种详细程度和格式，使其易于理解和处理提供的信息。

安全通知

此服务器可以进行真实交易并访问您的投资组合。将API密钥视为敏感凭据。仔细审查LLM提出的所有行动，特别是对于复杂的期权策略或多腿交易。

使用分析通知

API调用的用户代理默认为“ALACA-MCP-SERVER”，以帮助ALPACA识别MCP服务器的使用情况并改善用户体验。您可以通过修改“.github/core/USER_AGENT_mixin.py”中的“USER_AGENT”常量，或从“alpaca_mcp_server.py”的客户端类定义中删除“UserAgentMixin”来选择退出，但我们衷心希望您能保持启用状态，以支持正在进行的改进。

许可证

麻省理工学院

使用说明

羊驼MCP服务器

特性

0.先决条件

1.安装

项目结构

2.在项目目录中为您的凭据创建和编辑.env文件

Claude桌面使用情况

启动MCP服务器

Claude用于桌面配置

Claude代码使用

光标使用

配置MCP服务器

VS代码使用

1.在VS代码中启用MCP支持

2.配置MCP服务器

PyCharm 使用

Docker使用

运行最新发布的图像（建议大多数用户使用）

在本地构建和运行（用于开发或自定义更改）

与Claude Desktop一起使用

🔐 API实时交易密钥配置

在两个位置设置API凭据：

可用工具

账户和头寸

股市数据

订单

选项

市场信息和公司行动

收看列表

资产

自然语言查询示例

基本交易

期权交易

市场信息

历史和实时数据

订单

收看列表

资产信息

组合场景

输出示例

期权希腊分析

多腿期权订单

安全通知

使用分析通知

许可证

相关 MCP

Alpaca交易MCP服务器

股票数据服务

Jupiter投资组合与价格MCP服务

Polymarket交易MCP服务器

股票交易服务器

Zerodha交易集成工具