trader-broker

trader-broker

Order Executor 是此工具包中唯一可能导致真实订单成交的技能，因此规则最严格。每笔订单都必须依次通过以下三道独立关卡，缺一不可：

1. trader-risk 今天已通过这笔确切的订单（通过指纹匹配）。
2. 用户在聊天中明确输入了是，确认这笔订单。
3. 用户在 Claude 自己的权限卡片上点击了“允许一次”，该卡片会在订单工具设为“需要批准”时出现。

用户说两次“是”，规则通过一次。没有“是”，就没有订单。

下方的 ${CLAUDE_SKILL_DIR} 是此技能的文件夹（SKILL.md 所在位置）。

python3 "${CLAUDE_SKILL_DIR}/ticket.py" show                     # every ticket, READY or not
python3 "${CLAUDE_SKILL_DIR}/ticket.py" approve --index 1 --reply "yes"
python3 "${CLAUDE_SKILL_DIR}/ticket.py" result --index 1 --status placed --broker-id ID
python3 "${CLAUDE_SKILL_DIR}/ticket.py" fill --symbol AAPL --side buy --qty 3.6628 --price 341.27
python3 "${CLAUDE_SKILL_DIR}/ticket.py" log

ticket.py 从不与经纪商通信。它会生成订单票据、检查回复是否确实针对这笔订单表示同意，并将日志保存在 trader/state/broker.json 中。

设置 A：Alpaca（官方 MCP 服务，Claude Desktop）

Alpaca 自己的服务是 github.com/alpacahq/alpaca-mcp-server（MIT）。它在用户的电脑上通过 Claude Desktop 运行。它不在 Claude 的连接器目录中。除非另有说明，否则它使用模拟账户进行交易。

1. 用户创建 Alpaca 账户，并在 Alpaca 控制面板中创建模拟交易 API 密钥。模拟密钥与实盘密钥是分开的。
2. 用户安装 uv（它会提供 uvx），请访问 docs.astral.sh/uv。
3. 在 Claude Desktop 中：Settings > Developer > Edit Config。此操作会打开 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/， Windows：%APPDATA%\Claude\）。用户添加此代码块（此处的 claude_desktop_config.example.json 中也有该代码块），并在文件中输入自己的密钥：

{
  "mcpServers": {
    "alpaca": {
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "paste your paper key here, in this file only",
        "ALPACA_SECRET_KEY": "paste your paper secret here, in this file only",
        "ALPACA_PAPER_TRADE": "true",
        "ALPACA_TOOLSETS": "account,trading,stock-data"
      }
    }
  }
}

env 代码块会将密钥作为环境变量传递给服务。 切勿在聊天中输入密钥。 不要询问密钥，不要将此文件读回到对话中；如果用户还是粘贴了密钥，请告诉他们删除该消息，并在 Alpaca 控制面板中创建新密钥。 ALPACA_PAPER_TRADE 默认值已经是 true；将它写出来可以让这一设置显而易见。ALPACA_TOOLSETS 为可选项，用于隐藏用户不需要的工具。 4. 重启 Claude Desktop。 5. 设置工具权限。 打开 Customize > Connectors（旧版本中为 Settings > Connectors），打开 alpaca，并为每个工具选择 Always allow、Needs approval 或 Blocked：

• place_stock_order：Needs approval。切勿设为 Always allow。
• 其他所有会下单、更改、取消或平仓的工具 （cancel_order_by_id、close_position、update_account_config）：Needs approval。
• place_option_order、place_crypto_order、close_all_positions、 cancel_all_orders、exercise_options_position：除非用户有理由并明确提出，否则设为Blocked。
• 只读工具（get_account_info、get_all_positions、get_stock_snapshot、 get_stock_latest_quote）：设为 Always allow 没问题。

6. 进行检查：让 Claude 查询 Alpaca 账户信息（只读），并在 Alpaca 控制面板中确认这是模拟账户。

如果使用 Claude Code 而不是 Claude Desktop，请在 .claude/settings.json 中将订单工具设为 ask："permissions": {"ask": ["mcp__alpaca__place_stock_order"]}，并且绝不要将订单工具放入 allow。

设置 B：Interactive Brokers（Claude 目录中的连接器）

Interactive Brokers 发布了经过验证的连接器：claude.ai/directory/interactive-brokers （连接器 URL https://api.ibkr.com/v1/api/mcp）。请通过 Customize > Connectors > Browse connectors 添加，并在那里登录 IBKR，不要在聊天中登录。 其页面说明，Claude 可以起草交易指令并将其发送到用户的 IBKR 账户，供用户审核和批准；Claude 不会直接向市场提交订单。因此，使用 IBKR 时，最终的确认也要在 IBKR 中完成。在 trader/config.json 中设置 "broker": "ibkr"；如果 IBKR 要求提供股数，请使用 --whole-shares。也请将用于起草订单的工具设为 Needs approval。

每个订单的步骤

1. ticket.py show。只有 READY 票据才能展示给用户。状态为 NOT READY 或 BLOCKED 的票据应退回 /trader-risk。
2. 展示一张票据并询问：“要下这笔订单吗？请回复是或否。” 每次只问一个订单。 绝不提供“全部同意”选项。
3. 运行 ticket.py approve --index N --reply "<the user's reply, word for word>"。 如果输出“Not recorded”，说明该回复并非明确同意这笔订单（例如“当然可以”、“全部同意”， 或者回复中提到的是不同的股票或金额）。再次询问。绝不能自行把回复解释成同意。
4. 只有在输出“Recorded your yes”后，才能调用 place_stock_order，并严格使用 票据打印的 JSON。Claude 的卡片会显示“Allow once”或“Deny”。
5. 记录处理结果：ticket.py result --index N --status placed --broker-id <id from the response>；如果用户点击了 Deny，则使用 --status denied； 如果出错，则使用 --status failed 并附上 --note。失败的订单未经重新检查并获得新的同意， 不得重试。
6. 确认成交后（通过工具响应，或之后从 get_all_positions 获取）， ticket.py fill 会将其作为税务批次添加到 trader/portfolio.json，供 trader-tax 使用。 然后处理下一张票据。

示例：流程

ORDER 1 of 5, PAPER account, Alpaca
  BUY $1,250 of AAPL, market order, good for today
  READY: trader-risk PASS, waiting for your yes
  Claude will call place_stock_order with exactly:
    {"symbol": "AAPL", "side": "buy", "notional": "1250",
     "type": "market", "time_in_force": "day"}

用户回复“是”。Claude 会记录该回复，调用 place_stock_order，卡片上会显示 “Claude 想要使用 Place stock order”，并附上该 JSON 和两个按钮：Allow once、Deny。 点击 Allow once 会将订单发送到账户模拟交易环境。

绝不执行的操作

• 未经过全部三道关卡，绝不下单；一次同意绝不用于两个订单。
• 绝不通过计划任务或后台任务下单：因为无人在那里回复同意。
• 绝不索取、读取、存储或复述 API 密钥或密码。
• 绝不将 ALPACA_PAPER_TRADE 或 "paper" 切换为实盘。用户必须自行操作。
• 绝不自行调用 close_all_positions、cancel_all_orders、期权或加密货币订单工具。

安全

• 这是用于教育和提供工具的内容，不构成财务建议。此处的任何订单都不是投资建议，也不承诺回报。
• 默认使用模拟交易（"paper": true，ALPACA_PAPER_TRADE 为 true）。是否转为实盘由用户自行决定。
• 除 trader-broker 外，此工具包中没有任何内容会下单；且只有同时满足以下三项条件时才会下单：trader-risk 当天通过了该笔确切订单；用户在聊天中针对该笔订单明确输入了同意；用户在 Claude 自身的卡片上点击了 Allow once，因为订单工具设置为“Needs approval” （Customize > Connectors > tool permissions）。绝不要将订单工具设为“Always allow”。
• 除非配置允许且用户确认，否则不进行期权、保证金、卖空或杠杆交易。
• 经纪商密钥应保存在环境变量或 Claude Desktop 配置中，绝不能出现在聊天中。