Alpaca MCP Server

Alpaca MCP 服务

一个用于 Alpaca Trading API 的 Model Context Protocol (MCP) 服务，可与 AI 助手和开发工具无缝集成。

✅ 兼容性

已在运行 macOS 的 Apple Silicon M1 Pro 笔记本电脑上测试并验证可用。

功能

• 账户信息：获取实时账户详情、购买力、权益和状态
• 投资组合管理：查看当前持仓并跟踪盈亏
• 市场数据：获取包含买卖价差的实时股票报价
• 订单管理：列出并监控近期订单
• 模拟交易支持：通过模拟交易 API 提供安全的测试环境
• 支持实盘交易：兼容实盘交易（请谨慎使用）

安装

先决条件

pip install alpaca-trade-api

快速开始

1. 克隆代码库：

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

2. 设置 Alpaca API 凭据：

创建环境变量，或将其添加到 shell 配置文件中：

export APCA_API_KEY_ID="your_api_key_here"
export APCA_API_SECRET_KEY="your_secret_key_here"
export APCA_API_BASE_URL="https://paper-api.alpaca.markets"  # Paper trading
# export APCA_API_BASE_URL="https://api.alpaca.markets"      # Live trading

3. 测试服务：

python alpaca_mcp_server.py

MCP 集成

适用于 Cline/Claude Dev Tools

添加到 MCP 设置 JSON 中：

{
  "mcpServers": {
    "alpaca": {
      "command": "python",
      "args": ["/path/to/alpaca-mcp-server/alpaca_mcp_server.py"],
      "env": {
        "APCA_API_KEY_ID": "your_api_key_here",
        "APCA_API_SECRET_KEY": "your_secret_key_here",
        "APCA_API_BASE_URL": "https://paper-api.alpaca.markets"
      }
    }
  }
}

适用于 Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "alpaca": {
      "command": "python",
      "args": ["/path/to/alpaca-mcp-server/alpaca_mcp_server.py"],
      "env": {
        "APCA_API_KEY_ID": "your_api_key_here",
        "APCA_API_SECRET_KEY": "your_secret_key_here",
        "APCA_API_BASE_URL": "https://paper-api.alpaca.markets"
      }
    }
  }
}

可用工具

1. get_account

获取全面的账户信息，包括：

• 账户状态和账号
• 购买力和可用现金
• 投资组合权益和价值
• 模式日交易者状态
• 当日交易次数
• SMA（特殊备忘账户）

2. get_positions

查看当前股票持仓，包括：

• 股票代码和数量
• 当前市值
• 成本基础和盈亏
• 未实现收益/亏损
• 当前股价
• 持仓方向（多头/空头）

3. get_quote

获取任意股票代码的实时市场报价：

• 买入价和卖出价
• 买入量和卖出量
• 价格价差计算
• 报价时间戳

参数：

• symbol（必填）：股票代码（例如："AAPL"、"TSLA"、"NVDA"）

4. get_orders

列出近期订单并支持筛选：

• 订单 ID 和状态
• 股票代码和数量
• 订单类型和方向
• 成交信息
• 提交时间戳

参数：

• status（可选）："open"、"closed" 或 "all"（默认："all"）
• limit（可选）：订单数量上限（默认：10）

API 凭据

获取 Alpaca API 密钥

1. 在 Alpaca Markets 注册
2. 前往控制面板并打开 "API Keys"
3. 为模拟交易或实盘交易生成新的 API 密钥
4. 复制 API Key ID 和 Secret Key

环境设置

选项 1：环境变量

export APCA_API_KEY_ID="PK..."
export APCA_API_SECRET_KEY="..."
export APCA_API_BASE_URL="https://paper-api.alpaca.markets"

选项 2：.env 文件

APCA_API_KEY_ID=PK...
APCA_API_SECRET_KEY=...
APCA_API_BASE_URL=https://paper-api.alpaca.markets

安全与模拟交易

**⚠️ 重要提示：**为确保安全，本服务默认使用模拟交易模式。模拟交易使用虚拟资金，非常适合测试和开发。

要切换到实盘交易，请将基础 URL 更改为：

APCA_API_BASE_URL=https://api.alpaca.markets

只有在确信配置正确并准备好使用真实资金交易时，才使用实盘交易。

故障排除

常见问题

1. “Missing API credentials”错误：

   • 确保已正确设置环境变量
   • 检查变量名称是否完全匹配：APCA_API_KEY_ID、APCA_API_SECRET_KEY

2. “Connection failed”错误：

   • 确认 API 密钥有效
   • 检查网络连接
   • 确保使用了适用于模拟/实盘交易的正确基础 URL

3. “Module not found”错误：

   • 安装所需依赖：pip install alpaca-trade-api

测试服务

你可以使用 JSON-RPC 手动测试服务：

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | python alpaca_mcp_server.py

预期响应应包含可用工具。

开发

项目结构

alpaca-mcp-server/
├── alpaca_mcp_server.py    # Main MCP server
├── README.md               # This documentation
├── requirements.txt        # Python dependencies
└── examples/              # Usage examples

贡献

1. Fork 此代码库
2. 创建功能分支
3. 进行修改
4. 使用模拟交易进行全面测试
5. 提交拉取请求

许可证

MIT License - 详情请参阅 LICENSE 文件。

支持

• 问题反馈：GitHub Issues
• Alpaca API 文档：Alpaca Markets API
• MCP 协议：Model Context Protocol

免责声明

本软件仅用于教育和开发目的。使用实盘交易功能时，您交易的是真实资金。请务必先通过模拟交易进行充分测试。作者不对任何财务损失负责。