项目简介

这个项目是一个基于 Model Context Protocol (MCP) 的服务器，专门为 Alpaca 交易 API 设计。它允许大型语言模型（如 Claude Desktop, Cursor, VS Code）通过自然语言与 Alpaca 的交易基础设施进行无缝交互。您可以利用它进行股票和期权交易、管理投资组合、监控市场数据等。

主要功能点

实时市场数据: 获取股票的实时报价、交易和K线数据，以及期权合约的报价和希腊字母。
历史市场数据: 查询股票的历史价格、交易记录和公司行为（如财报、拆股）。
账户管理: 查看账户余额、购买力、资金状况、持仓及交易历史。
持仓管理: 获取单个持仓的详细信息，或按数量/百分比清算部分或全部持仓。
订单管理: 下达股票和期权订单（市价单、限价单），取消订单，并检索完整的订单历史。
期权交易: 搜索和查看期权合约，下达多腿期权策略。
市场状态与公司公告: 查询市场开闭时间、市场日历，以及查看即将发生或已发生的公司公告。
关注列表管理: 创建、更新和查看个人关注列表，管理多个资产追踪列表。
资产搜索: 查询股票和其他 Alpaca 支持资产的详细信息。

安装步骤

环境准备: 确保您的系统已安装 Python 3.10 或更高版本。
克隆仓库: 将项目仓库克隆到本地。

创建并激活虚拟环境:

使用 pip (传统方式):

python3 -m venv myvenv
source myvenv/bin/activate  # 在 Windows 上使用: myvenv\Scripts\activate
pip install -r requirements.txt

使用 uv (现代、更快): 您需要先安装 uv。请参考 uv 官方安装指南。

uv venv myvenv
source myvenv/bin/activate # 在 Windows 上使用: myvenv\Scripts\activate
uv pip install -r requirements.txt

配置 Alpaca API 密钥:

复制 '.env.example' 文件到 '.env':

cp .env.example .env

编辑 '.env' 文件，填入您的 Alpaca API 密钥和秘密密钥，并根据需要设置 'ALPACA_PAPER_TRADE' 为 'True' (模拟交易) 或 'False' (实盘交易)。

ALPACA_API_KEY = "您的Alpaca API Key"
ALPACA_SECRET_KEY = "您的Alpaca Secret Key"
ALPACA_PAPER_TRADE = True
# 其他配置可以保持默认或根据您的需求修改

服务器配置

MCP服务器需要通过MCP客户端（如 Claude Desktop, Cursor, VS Code）进行配置才能使用。以下是常见的配置方式示例。请根据您使用的MCP客户端的官方文档进行具体操作。

MCP客户端配置示例 (JSON格式，以 Claude Desktop 为例): 要将 Alpaca MCP 服务器与您的 MCP 客户端连接，您需要提供服务器的启动命令和相关参数。这些配置通常在客户端的设置或配置文件中完成。

本地使用 (Stdio 传输 - 推荐): 这种方式会在本地启动 MCP 服务器并使用标准输入/输出进行通信。

{
  "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": "您的Alpaca API Key",
        "ALPACA_SECRET_KEY": "您的Alpaca Secret Key"
      }
    }
  }
}

'command': 指向您虚拟环境中的 Python 解释器路径。
'args': 包含启动 MCP 服务器主脚本的路径。
'env': 用于设置 Alpaca API 密钥等环境变量。

远程使用 (HTTP 传输): 如果 MCP 服务器部署在远程机器上，或者您希望通过 HTTP 协议进行通信。

{
  "mcpServers": {
    "alpaca": {
      "transport": "http",
      "url": "http://您的服务器IP地址:8000/mcp",
      "env": {
        "ALPACA_API_KEY": "您的Alpaca API Key",
        "ALPACA_SECRET_KEY": "您的Alpaca Secret Key"
      }
    }
  }
}

'transport': 指定为 'http'。
'url': MCP 服务器的访问地址和端口。
'env': 用于设置 Alpaca API 密钥等环境变量。

请务必将上述路径替换为您的实际项目路径，并填入正确的 Alpaca API 密钥。

基本使用方法

启动 MCP 服务器:

本地 (Stdio 传输 - 默认): 在项目根目录下打开终端，运行：

python alpaca_mcp_server.py

远程 (HTTP 传输): 在项目根目录下打开终端，运行：

python alpaca_mcp_server.py --transport http --host 0.0.0.0 --port 8000

( '--host 0.0.0.0' 表示监听所有网络接口，以便远程访问，您可以根据需要调整 'host' 和 'port'。)

在 MCP 客户端中交互: 配置好 MCP 客户端后，您可以直接在 LLM 界面中通过自然语言与服务器进行交互，例如：
- "What is my account balance?" (查询账户信息)
- "Show me the latest quote for AAPL." (获取苹果股票最新报价)
- "Buy 10 shares of MSFT at market price." (市价购买微软股票)
- "Get the historical daily bars for GOOGL for the last 30 days." (获取谷歌过去30天的日K线数据)
- "List all open positions." (列出所有开放持仓)

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息