一款面向 Alpaca 交易 API 的综合模型上下文协议（MCP）服务器。通过 Claude、Cursor 和 VS Code 等 AI 助手，实现自然语言的交易操作。支持股票、期权、加密货币、投资组合管理以及实时市场数据。

Alpaca MCP 服务器 v2 已发布。 此版本基于 FastMCP 和 OpenAPI 完全重写。如果您正在从 v1 升级，请阅读升级指南——工具名称、参数和配置均已更改。

目录

• 从 V1 升级
• 先决条件
• 获取您的 API 密钥
• 设置
• 配置
• 功能
• 示例提示
• 可用工具
• 测试
• 项目结构
• 故障排除
• 披露

---

从 V1 升级

V2 是使用 FastMCP 和 OpenAPI 构建的全新重写版本。V1 中的所有工具在 V2 中均不存在——工具名称、参数和模式都已更改。如果您的设置依赖于特定的 V1 工具名称或参数，则无法将 V2 作为直接替代品。

变化对比

方面	V1	V2
工具名称	手工定义（如 get_account_info）	基于规范派生并可覆盖（如 get_account_info——名称可能重复，但模式不同）
参数	自定义模式	与 Alpaca API 规范一致
配置	.env 文件 + init 命令	仅通过 MCP 客户端配置中的环境变量进行配置
工具过滤	不支持	使用 ALPACA_TOOLSETS 环境变量
白名单机制	不支持	使用 ALPACA_TOOLSETS 来限制可用工具

如何避免在 V2 中沿用 V1 的用法

MCP 客户端会动态地从服务器发现工具。不存在用于“白名单”工具名称的配置文件——客户端只会获取服务器暴露的工具列表。为避免您的客户端或 AI 助手错误地使用 V2：

1. 请勿复用 V1 配置——将 V2 视为全新的服务器。更新您的 MCP 客户端配置以使用新的命令和参数；移除任何基于 .env 或 init 的设置。
2. 清除工具缓存——切换后重启您的 MCP 客户端（Claude Desktop、Cursor、VS Code 等），以便它获取最新的工具列表，而不是继续使用过时的缓存。
3. 开启新的聊天/会话——现有对话可能仍缓存着旧工具名称的引用。请开始一个新的聊天，让 LLM 能够看到当前的 V2 工具及其模式。
4. 更新自定义指令和规则——如果您有 Cursor 规则、Claude 指令或其他提及特定 V1 工具名称的提示（例如“使用 get_account_info”），请将其更新为匹配 V2 工具名称，或移除这些引用，让 LLM 根据上下文自行发现工具。
5. 使用 ALPACA_TOOLSETS 限制工具——如果您之前曾限制助手可用的功能，V2 支持通过 ALPACA_TOOLSETS 环境变量进行服务器端过滤。有关工具集列表，请参阅配置 > 工具集过滤。

总结

请假设与 V1 无向后兼容性。为 V2 重新配置您的 MCP 客户端，重启它，并使用全新的会话。请查看可用工具部分以获取当前的工具列表。

如果您有自定义的 V1 工作流

如果您曾记录允许使用的工具、编写按名称调用工具的脚本，或围绕特定 V1 工具/参数形状构建提示——请视这些内容为已过时。请使用下方列出的可用工具以及服务器公开的当前参数模式重新创建它们。

继续使用 V1

如果您需要继续使用 V1，请在您的 MCP 客户端配置中锁定到最后一个 V1 版本（例如：uvx alpaca-mcp-server==1.x.x serve）。V1 仍然可在 PyPI 上获取，供现有设置使用。

---

先决条件

• Python 3.10+（安装指南）
• uv（安装指南）
• Alpaca 交易 API 密钥（免费模拟交易账户）
• MCP 客户端（Claude Desktop、Cursor、VS Code 等）

获取您的 API 密钥

1. 访问 Alpaca 控制台
2. 创建一个免费的模拟交易账户
3. 在控制台生成 API 密钥

设置

将服务器添加到您的 MCP 客户端配置中，然后重启客户端。无需 init 命令，也不再使用 .env 文件——凭据只需在一处设置即可。

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（Mac）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "alpaca": {
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "your_alpaca_api_key",
        "ALPACA_SECRET_KEY": "your_alpaca_secret_key"
      }
    }
  }
}

Cursor

只需点击几下即可从 Cursor 目录 安装，或将以下内容添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "alpaca": {
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "your_alpaca_api_key",
        "ALPACA_SECRET_KEY": "your_alpaca_secret_key"
      }
    }
  }
}

VS Code

在项目根目录下创建 .vscode/mcp.json。请参阅官方文档。

{
  "mcp": {
    "servers": {
      "alpaca": {
        "type": "stdio",
        "command": "uvx",
        "args": ["alpaca-mcp-server"],
        "env": {
          "ALPACA_API_KEY": "your_alpaca_api_key",
          "ALPACA_SECRET_KEY": "your_alpaca_secret_key"
        }
      }
    }
  }
}

PyCharm

请参阅官方指南。

1. 转到 文件 → 设置 → 工具 → 模型上下文协议 (MCP)
2. 添加新服务器：
   • 类型: stdio
   • 命令: uvx
   • 参数: alpaca-mcp-server
3. 设置环境变量：

   ALPACA_API_KEY=your_alpaca_api_key
   ALPACA_SECRET_KEY=your_alpaca_secret_key
   

Claude Code

claude mcp add alpaca --scope user --transport stdio uvx alpaca-mcp-server \
  --env ALPACA_API_KEY=your_alpaca_api_key \
  --env ALPACA_SECRET_KEY=your_alpaca_secret_key

通过 Claude Code CLI 中的 /mcp 命令进行验证。

Gemini CLI

请参阅Gemini CLI 的 MCP 文档。

将以下内容添加到你的 settings.json：

{
  "mcpServers": {
    "alpaca": {
      "type": "stdio",
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "your_alpaca_api_key",
        "ALPACA_SECRET_KEY": "your_alpaca_secret_key"
      }
    }
  }
}

Docker

git clone https://github.com/alpacahq/alpaca-mcp-server.git
cd alpaca-mcp-server
docker build -t mcp/alpaca:latest .

将以下内容添加到你的 MCP 客户端配置中：

{
  "mcpServers": {
    "alpaca": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "ALPACA_API_KEY=your_key",
        "-e", "ALPACA_SECRET_KEY=your_secret",
        "-e", "ALPACA_PAPER_TRADE=true",
        "mcp/alpaca:latest"
      ]
    }
  }
}

配置

所有配置均通过 MCP 客户端配置中的环境变量进行设置，不会向磁盘写入任何文件。

变量	必需	默认值	描述
ALPACA_API_KEY	是	—	你的 Alpaca API 密钥
ALPACA_SECRET_KEY	是	—	你的 Alpaca 秘密密钥
ALPACA_PAPER_TRADE	否	true	设置为 false 以进行实盘交易
ALPACA_TOOLSETS	否	all	用逗号分隔的要启用的工具集列表

切换到实盘交易

更新 MCP 客户端配置中的 env 块并重启：

{
  "env": {
    "ALPACA_API_KEY": "your_live_api_key",
    "ALPACA_SECRET_KEY": "your_live_secret_key",
    "ALPACA_PAPER_TRADE": "false"
  }
}

工具集过滤

默认情况下，所有工具都已启用。若要限制服务器仅使用特定工具集，请设置 ALPACA_TOOLSETS：

{
  "env": {
    "ALPACA_API_KEY": "...",
    "ALPACA_SECRET_KEY": "...",
    "ALPACA_TOOLSETS": "stock-data,crypto-data"
  }
}

可用工具集如下：

工具集	描述
account	账户信息、配置、投资组合历史、活动
trading	订单、持仓、期权行权
watchlists	关注列表的增删改查操作
assets	资产查询、期权合约、日历、市场时钟
stock-data	股票K线、报价、成交、快照、筛选器
crypto-data	加密货币K线、报价、成交、快照、订单簿
options-data	期权K线、报价、成交、快照、链、交易所代码
corporate-actions	公司公告

功能

• 市场数据 — 实时股票、加密货币和期权的报价、成交及K线。灵活时间框架的历史数据。期权希腊字母及隐含波动率。
• 账户管理 — 查看余额、可买金额、账户状态及投资组合历史。
• 订单管理 — 下达市价单、限价单、止损单、止损限价单及追踪止损单，适用于股票、加密货币和期权。可单独或批量取消订单。
• 期权交易 — 按到期日/执行价/类型搜索合约。可构建单腿或多腿策略。获取最新报价、希腊字母及隐含波动率。
• 加密货币交易 — 市价单、限价单及止损限价单，支持GTC/IOC指令。可按数量或名义价值下单。
• 头寸管理 — 查看、平仓或清算头寸。行使期权合约。
• 市场状态 — 市场开盘/收盘时间、日历、公司公告。
• 关注列表 — 创建、更新和管理关注列表。
• 资产搜索 — 查询股票、ETF、加密货币和期权的详细信息，并支持筛选。

示例提示

基础交易

1. 我在Alpaca上的当前账户余额和可买金额是多少？
2. 展示我在Alpaca账户中的当前持仓。
3. 以市价买入5股AAPL。
4. 以限价300美元卖出5股TSLA。
5. 取消所有未成交的股票订单。
6. 取消ID为abc123的订单。
7. 清空我在GOOGL上的全部头寸。
8. 平掉我在NVDA上10%的仓位。
9. 下单以450美元的价格买入100股MSFT的限价单。
10. 下单以市价卖出25股META。

加密货币交易

1. 下单以市价买入0.01枚ETH/USD。
2. 下单以11万美元的价格卖出0.01枚BTC/USD的限价单。

期权交易

1. 展示AAPL下月到期的可用期权合约。
2. 获取AAPL250613C00200000期权的最新报价。
3. 检索SPY250627P00400000期权的快照信息。
4. 清空我持有的下周到期的2份QQQ看涨期权合约。
5. 下单以市价买入一份下周五到期的AAPL看涨期权。
6. TSLA250620P00500000期权的希腊字母指标是什么？
7. 查找行权价在当前市场价格上下5%范围内的TSLA期权合约。
8. 获取2025年6月16日当周到期、行权价在市场价格上下10%范围内的SPY看涨期权。
9. 使用AAPL6月6日到期的期权构建牛市看涨价差策略：一份行权价为190.00，另一份行权价为200.00。
10. 行使我的NVDA看涨期权合约NVDA250919C001680。

市场信息

若要获取最新的15分钟行情数据，您需要订阅Algo Trader Plus计划。

1. 今天市场的开盘和收盘时间分别是几点？
2. 展示下周的市场日历。
3. 展示过去3个月内AAPL、MSFT和GOOGL的现金分红及股票拆分情况。
4. 获取SPY在过去一年内发生的所有公司行为，包括分红、拆股及任何并购事件。
5. SPY未来6个月内计划进行的公司行为有哪些？

历史与实时数据

1. 展示AAPL最近5个交易日的日线价格走势。
2. TSLA昨日的收盘价是多少？
3. 获取GOOGL的最新K线。
4. NVDA的最新成交价是多少？
5. 展示MSFT的最新报价。
6. 检索AMD最近100笔成交记录。
7. 展示AMZN过去2小时内的1分钟K线。
8. 获取TSLA上周二至上周五的5分钟盘中K线。
9. 获取AAPL的综合股票快照，将最新报价、最新成交、1分钟K线、日线以及前一日日线整合到一个视图中。
10. 对比TSLA、NVDA和MSFT的市场快照，分析它们当前的买卖价差、最新成交价及当日表现。

订单

1. 展示我本周所有未成交及已成交的订单。
2. 我有哪些关于AAPL的订单？
3. 列出我过去3天内下达的所有限价单。
4. 按订单状态筛选：仅显示已成交的订单。
5. 获取昨天的订单历史。

自选列表

目前，您只能通过Alpaca的交易API来查看和更新通过该API创建的交易自选列表。

1. 创建一个名为“科技股”的新自选列表，包含AAPL、MSFT和NVDA。
2. 更新我的“科技股”自选列表，加入TSLA和AMZN。
3. 我的“分红精选”自选列表里都有哪些股票？
4. 从我的“成长型投资组合”自选列表中移除META。
5. 列出我现有的所有自选列表。

资产信息

1. 搜索关于‘AAPL’资产的详细信息。
2. 展示按交易量排名前5位的可交易加密货币资产。
3. 获取所有纳斯达克上市的美国股票资产，并筛选出其中可交易的证券。

综合场景

1. 获取今日的市场时钟，并在我以340美元的限价买入TSLA之前，展示我的可买金额。
2. 使用SPY7月3日到期的期权构建牛市看涨价差策略：一份卖出价比当前SPY价格高5%，另一份买入价比当前价格低3%。

可用工具

账户与投资组合

• get_account_info — 账户余额、保证金及账户状态
• get_account_config — 交易限制、保证金设置、PDT检查
• update_account_config — 更新账户配置设置
• get_portfolio_history — 投资组合权益及盈亏随时间的变化
• get_account_activities — 成交记录、股息、资金划转
• get_account_activities_by_type — 按类型筛选的账户活动

交易（订单）

• get_orders — 带过滤条件的订单列表
• get_order_by_id — 根据订单ID获取单个订单
• get_order_by_client_id — 根据客户订单ID获取单个订单
• replace_order_by_id — 替换现有未成交订单
• cancel_order_by_id — 取消指定订单
• cancel_all_orders — 取消所有未成交订单
• place_stock_order — 股票/ETF（市价、限价、止损、止损限价、追踪止损、括号单）
• place_crypto_order — 加密货币（市价、限价、止损限价）
• place_option_order — 期权（单腿或多腿）

持仓

• get_all_positions — 当前所有持仓
• get_open_position — 特定持仓的详细信息
• close_position — 平仓特定持仓
• close_all_positions — 清空整个投资组合
• exercise_options_position — 行权持有的期权合约
• do_not_exercise_options_position — 不行权指令

自选列表

• create_watchlist — 创建新的自选列表
• get_watchlists — 列出所有自选列表
• get_watchlist_by_id — 获取特定自选列表
• update_watchlist_by_id — 更新自选列表
• delete_watchlist_by_id — 删除自选列表
• add_asset_to_watchlist_by_id — 向自选列表添加资产
• remove_asset_from_watchlist_by_id — 从自选列表移除资产

资产与市场信息

• get_all_assets — 列出资产，可选过滤
• get_asset — 特定资产的详细信息
• get_option_contracts — 标的证券的期权合约
• get_option_contract — 根据标的或ID获取单个期权合约
• get_calendar — 指定日期范围内的市场日历
• get_clock — 当前市场状态及下一交易时段的开收盘时间
• get_corporate_action_announcements — 公司行为公告
• get_corporate_action_announcement — 根据ID获取单个公告

股票数据

• get_stock_bars — 历史OHLCV分时数据
• get_stock_quotes — 历史买卖盘报价
• get_stock_trades — 历史成交记录
• get_stock_latest_bar — 最新一分钟K线
• get_stock_latest_quote — 最新报价
• get_stock_latest_trade — 最新成交
• get_stock_snapshot — 综合快照
• get_most_active_stocks — 按成交量/成交次数最活跃的股票
• get_market_movers — 涨幅最大和跌幅最大的股票

加密货币数据

• get_crypto_bars — 历史OHLCV分时数据
• get_crypto_quotes — 历史报价
• get_crypto_trades — 历史成交记录
• get_crypto_latest_bar — 最新一分钟K线
• get_crypto_latest_quote — 最新报价
• get_crypto_latest_trade — 最新成交
• get_crypto_snapshot — 综合快照
• get_crypto_latest_orderbook — 最新委托簿

期权数据

• get_option_bars — 历史OHLCV分时数据
• get_option_trades — 历史成交记录
• get_option_latest_trade — 最新成交
• get_option_latest_quote — 包含买卖盘及交易所信息的最新报价
• get_option_snapshot — 包含希腊字母及隐含波动率的快照
• get_option_chain — 标的证券的完整期权链
• get_option_exchange_codes — 交易所代码与名称的映射

公司行为

• get_corporate_actions — 从市场数据中获取公司行为公告

测试

该项目包含多层测试套件，在每次拉取请求时都会在CI中运行：

• 完整性测试 — 验证OpenAPI规范、工具集定义以及工具名称/描述覆盖之间的一致性。无需网络或凭证。
• 服务器构建测试 — 使用模拟凭证构建服务器，并验证暴露的工具数量是否正确。无需网络。
• 纸面API集成测试 — 对Alpaca纸面交易API执行真实调用，涵盖账户信息、市场数据、订单生命周期、自选列表、持仓等。需要ALPACA_API_KEY和ALPACA_SECRET_KEY。

本地运行完整测试套件：

# 核心测试（无需凭证）
pytest tests/test_integrity.py tests/test_server_construction.py -v

# 集成测试（需要纸面API密钥）
ALPACA_API_KEY=... ALPACA_SECRET_KEY=... pytest tests/ -m integration -v

项目结构

alpaca-mcp-server/
├── src/
│   └── alpaca_mcp_server/
│       ├── __init__.py
│       ├── cli.py            ← CLI入口点
│       ├── server.py         ← 基于OpenAPI规范构建的FastMCP服务器
│       ├── names.py          ← 工具名称和描述覆盖
│       ├── toolsets.py       ← 工具集→operationId白名单
│       ├── overrides.py      ← 用于复杂交易端点的手工工具
│       ├── market_data_overrides.py ← 用于历史数据的手工工具
│       └── specs/
│           ├── trading-api.json
│           └── market-data-api.json
├── tests/
│   ├── conftest.py           ← 共享fixture及纸面账户清理
│   ├── test_integrity.py     ← 规范↔工具集↔名称一致性检查
│   ├── test_server_construction.py ← 服务器构建验证
│   └── test_paper_integration.py   ← 纸面API集成测试
├── scripts/
│   └── sync-specs.sh        ← 下载最新OpenAPI规范
├── .github/
│   └── workflows/
│       └── ci.yml            ← CI流水线（核心+集成）
├── AGENTS.md                 ← 编程代理使用说明
├── pyproject.toml
└── README.md

故障排除

• 找不到uv/uvx：按照官方指南安装uv（https://docs.astral.sh/uv/getting-started/installation/），然后重启终端，使uv/uvx位于PATH中。
• 缺少凭证：在客户端的env块中设置ALPACA_API_KEY和ALPACA_SECRET_KEY。纸面模式默认为ALPACA_PAPER_TRADE = True。
• 客户端未加载新配置：更改后请重启客户端（Cursor、Claude Desktop、VS Code）。
• HTTP端口冲突：如果使用--transport streamable-http，请将--port更改为未被占用的端口。

公告

我们MCP服务器及连接的AI智能体生成的洞察仅供教育和信息参考之用，不应被视为投资建议。Alpaca不推荐任何特定的证券或投资策略。请在做出任何决策前自行进行尽职调查。所有提及的公司均独立运营，彼此之间不承担连带责任。

由于期权交易本身具有高风险，可能导致重大损失，因此并不适合所有投资者。在投资期权之前，请务必阅读《标准化期权的特点与风险》（期权披露文件）。

Alpaca不会编制、编辑、认可或批准第三方内容。Alpaca不保证第三方内容的准确性、时效性、完整性或实用性，且不对第三方网站上或通过其提供的任何内容、广告、产品或其他材料负责或承担法律责任。

所有投资均存在风险，证券或金融产品的过往表现并不能保证未来的结果或收益。没有任何投资策略能够确保实现其目标。请注意，分散投资并不能保证盈利，也不能避免亏损。投资于证券或其他金融产品时，始终存在资金损失的可能性。投资者在投资前应仔细考虑自身的投资目标和风险。

本算法的计算基于历史和实时市场数据，但可能无法涵盖所有市场因素，包括价格的突然波动、流动性限制或执行延迟等。模型假设，如波动率估算和股息处理方式，可能会影响其性能和准确性。由该算法生成的交易将受到经纪商执行流程、市场流动性、订单优先级以及时间延迟等因素的影响。这些因素可能导致实际成交价格或时间与预期出现偏差。用户有责任监控算法活动并充分了解相关风险。Alpaca对因使用本系统而产生的任何损失不承担任何责任。

过去的模拟回测结果并不保证未来的回报，实际结果可能会与分析结果有所不同。

纸面交易API由AlpacaDB, Inc.提供，无需真实资金，也不允许用户在市场上进行真实的证券交易。提供纸面交易API并不构成购买或出售任何证券、证券衍生品或期货产品，或任何形式的交易或投资建议、推荐或策略的要约或招揽；此类要约或招揽既未由AlpacaDB, Inc.或其任何关联公司提出，也未以任何方式得到其认可。通过纸面交易API所提供的信息，在AlpacaDB, Inc.或其任何关联公司（统称“Alpaca”）未获授权开展业务的司法管辖区内，均不构成任何形式的要约或招揽。

证券经纪服务由Alpaca Securities LLC（“Alpaca Securities”）提供，该公司是FINRA和SIPC的成员，为AlpacaDB, Inc.的全资子公司。技术和相关服务则由AlpacaDB, Inc.提供。

加密货币服务由Alpaca Crypto LLC（“Alpaca Crypto”）提供，这是一家经FinCEN注册的资金服务企业（NMLS # 2160858），也是AlpacaDB, Inc.的全资子公司。Alpaca Crypto并非SIPC或FINRA的成员。加密货币不同于股票，您的加密货币投资不受FDIC或SIPC的保护。加密货币资产波动性极高，具有高度投机性，存在较大的亏损风险，且不受FDIC或其他政府机构的保险保障。客户在使用这些服务前，应充分了解各种风险，包括本金损失、网络安全问题、监管动态以及数字资产技术的不断演变等。有关加密货币风险的更多信息，请点击此处。

在Alpaca Securities或Alpaca Crypto尚未注册或获得许可的司法管辖区内，本内容不构成购买或出售证券或加密货币，或开设经纪账户或加密货币账户的要约、招揽或建议。

隐私政策

有关Alpaca如何处理您的数据的信息，请参阅：

• 隐私政策
• 披露资料库

数据收集

• 收集的内容：用于API调用的用户代理字符串（‘ALPACA-MCP-SERVER’）
• 用途：用于识别MCP服务器的使用情况并改善用户体验
• 第三方共享：不会与第三方共享
• 保留期限：按照Alpaca的标准数据保留政策进行保留
• 退出机制：可通过修改“.github/core/user_agent_mixin.py”中的‘USER_AGENT’常量，或将‘UserAgentMixin’从客户端类定义中移除来退出

安全须知

本服务器可以执行真实交易并访问您的投资组合。请将您的API密钥视为敏感凭证。请仔细审查LLM提出的各项操作建议，尤其是涉及复杂期权策略或多腿交易时。

HTTP传输安全：在使用HTTP传输时，服务器默认绑定到本地主机（127.0.0.1:8000）以确保安全性。如需远程访问，您可以使用--host 0.0.0.0将服务器绑定到所有网络接口，或通过SSH隧道（ssh -L 8000:localhost:8000 user@server）进行连接，亦或设置带有身份验证的反向代理以实现安全访问。

支持

如遇问题或疑问，请通过support@alpaca.markets与我们联系。

GitHub问题：https://github.com/alpacahq/alpaca-mcp-server/issues
GitHub拉取请求：https://github.com/alpacahq/alpaca-mcp-server/pulls

MCP注册表元数据

mcp名称：io.github.alpacahq/alpaca-mcp-server

Alpaca MCP Server 快速上手指南

Alpaca MCP Server 是一个基于模型上下文协议（MCP）的服务端工具，允许你通过 AI 助手（如 Claude、Cursor、VS Code Copilot 等）使用自然语言进行股票、期权、加密货币的交易操作及市场数据查询。

注意：本文档针对 v2 版本。v2 是完全重构版，与 v1 不兼容（工具名称、参数及配置方式均已变更）。如果你正在从 v1 升级，请视为全新安装并清除旧的缓存配置。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：macOS, Windows, 或 Linux
• Python：版本 3.10 或更高 (下载链接)
• uv 包管理器：推荐使用的快速 Python 包管理工具 (安装指南)
  • 安装命令 (macOS/Linux): curl -LsSf https://astral.sh/uv/install.sh | sh
  • 安装命令 (Windows PowerShell): powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
• Alpaca 账户：需要拥有 Alpaca Trading API 密钥（免费模拟交易账户即可）。
• MCP 客户端：已安装支持 MCP 的 AI 编辑器或终端，例如：
  • Claude Desktop
  • Cursor
  • VS Code (需安装相关 MCP 扩展)
  • JetBrains IDEs (PyCharm 等)

获取 API 密钥

1. 访问 Alpaca Dashboard。
2. 注册并创建一个免费的模拟交易账户 (Paper Trading Account)。
3. 在仪表盘中生成你的 API Key 和 Secret Key。

安装与配置

Alpaca MCP Server v2 无需复杂的初始化命令或 .env 文件，所有配置直接写在 MCP 客户端的配置文件中。

1. Claude Desktop

编辑配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

添加以下内容：

{
  "mcpServers": {
    "alpaca": {
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "你的_ALPACA_API_KEY",
        "ALPACA_SECRET_KEY": "你的_ALPACA_SECRET_KEY",
        "ALPACA_PAPER_TRADE": "true"
      }
    }
  }
}

2. Cursor

编辑 ~/.cursor/mcp.json 或在 Cursor 设置中直接添加：

{
  "mcpServers": {
    "alpaca": {
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "你的_ALPACA_API_KEY",
        "ALPACA_SECRET_KEY": "你的_ALPACA_SECRET_KEY",
        "ALPACA_PAPER_TRADE": "true"
      }
    }
  }
}

3. VS Code

在项目根目录创建 .vscode/mcp.json 文件：

{
  "mcp": {
    "servers": {
      "alpaca": {
        "type": "stdio",
        "command": "uvx",
        "args": ["alpaca-mcp-server"],
        "env": {
          "ALPACA_API_KEY": "你的_ALPACA_API_KEY",
          "ALPACA_SECRET_KEY": "你的_ALPACA_SECRET_KEY",
          "ALPACA_PAPER_TRADE": "true"
        }
      }
    }
  }
}

4. 其他客户端简要配置

• PyCharm: 进入 File → Settings → Tools → Model Context Protocol (MCP)，新建服务器，类型选 stdio，命令填 uvx，参数填 alpaca-mcp-server，并在环境变量中添加 Key。
• Claude Code (CLI):

  claude mcp add alpaca --scope user --transport stdio uvx alpaca-mcp-server \
    --env ALPACA_API_KEY=你的_ALPACA_API_KEY \
    --env ALPACA_SECRET_KEY=你的_ALPACA_SECRET_KEY
  

• Docker:

  {
    "mcpServers": {
      "alpaca": {
        "command": "docker",
        "args": [
          "run", "--rm", "-i",
          "-e", "ALPACA_API_KEY=你的_KEY",
          "-e", "ALPACA_SECRET_KEY=你的_SECRET",
          "-e", "ALPACA_PAPER_TRADE=true",
          "mcp/alpaca:latest"
        ]
      }
    }
  }
  

基本使用

配置完成后，重启你的 MCP 客户端（关闭并重新打开编辑器或对话窗口），以确保加载最新的工具列表。

开启实盘交易（可选）

默认情况下，服务器运行在模拟交易模式 (ALPACA_PAPER_TRADE: true)。若需进行真实资金交易，请将配置中的该值改为 "false" 并使用实盘 API 密钥：

"env": {
  "ALPACA_API_KEY": "你的实盘_API_KEY",
  "ALPACA_SECRET_KEY": "你的实盘_SECRET_KEY",
  "ALPACA_PAPER_TRADE": "false"
}

功能示例

在 AI 聊天窗口中，你可以直接使用自然语言下达指令：

1. 查询账户状态

"帮我查看当前的账户余额和购买力。" "显示我目前的持仓情况。"

2. 获取市场数据

"查询苹果公司 (AAPL) 今天的股价走势和最新报价。" "给我看看比特币 (BTCUSD) 最近的交易量数据。"

3. 执行交易操作

"以市价买入 10 股特斯拉 (TSLA)。" "为微软 (MSFT) 设置一个限价买单，价格为 400 美元，数量 5 股。" "平仓我所有的亚马逊 (AMZN) 持仓。"

4. 期权与高级功能

"查找下个月到期的苹果看涨期权合约。" "列出我所有的观察列表。"

限制工具范围（可选）

如果你只想让 AI 访问特定功能（例如只读数据，不允许交易），可以在配置中添加 ALPACA_TOOLSETS 环境变量：

"env": {
  "ALPACA_API_KEY": "...",
  "ALPACA_SECRET_KEY": "...",
  "ALPACA_TOOLSETS": "stock-data,crypto-data,account"
}

可用工具集包括：account, trading, watchlists, assets, stock-data, crypto-data, options-data, corporate-actions。