trader-broker

trader-broker

注文執行ツールは、このパックで実際の注文につながる可能性がある唯一のスキルであり、そのため最も厳格です。注文が市場に届くのは、毎回、すべての注文について、次の3つの独立したゲートをすべて通過した後だけです。

1. trader-risk が今日、この正確な注文を承認していること（フィンガープリントで照合）。
2. チャットで、ユーザーがこの注文について明示的に「はい」と入力していること。
3. 注文ツールが「承認が必要」に設定されているため表示される、Claude 独自の権限カードで、ユーザーが「許可」を1回クリックしていること。

ユーザーによる「はい」が2回、ルールによる PASS が1回。はいがなければ、注文はありません。

以下の ${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. ユーザーが docs.astral.sh/uv から uv（uvx を提供します）をインストールします。
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 を選択して、各ツールに「常に許可」「承認が必要」「ブロック」のいずれかを設定します。

• place_stock_order：承認が必要。決して「常に許可」にしないでください。
• 何らかの操作を実行、変更、キャンセル、またはクローズするその他すべてのツール（cancel_order_by_id、close_position、update_account_config）：承認が必要。
• place_option_order、place_crypto_order、close_all_positions、cancel_all_orders、exercise_options_position：ユーザーに理由があり、そうするよう伝えた場合を除き、ブロック。
• 読み取り専用ツール（get_account_info、get_all_positions、get_stock_snapshot、get_stock_latest_quote）：「常に許可」で問題ありません。

6. 動作を確認します。Claude に Alpaca の口座情報を（読み取り専用で）尋ね、Alpaca ダッシュボードでペーパー口座であることを確認します。

Claude Desktop ではなく Claude Code を使う場合は、.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 を指定して数量を設定します。注文を下書きするツールも「承認が必要」に設定してください。

注文ごとの手順

1. ticket.py show を実行します。ユーザーに提示するのは READY チケットのみです。READY ではない、または BLOCKED のチケットは /trader-risk に戻します。
2. チケットを 1 件だけ表示し、「この注文を発注しますか？ yes または no で回答してください。」と尋ねます。質問 1 回につき注文は 1 件です。「すべてに yes」と答えるよう促してはいけません。
3. ticket.py approve --index N --reply "<the user's reply, word for word>" を実行します。「Not recorded」と表示された場合、その回答はこの注文に対する明示的な yes ではありません（たとえば、「sure」、「yes to all」、または別の銘柄や金額を指定した yes などです）。もう一度尋ねてください。回答を勝手に yes に変えてはいけません。
4. 「Recorded your yes」の後に限り、チケットに表示された JSON をそのまま使って place_stock_order を呼び出します。Claude のカードが表示されます。「Allow once」または「Deny」を選択します。
5. 結果を記録します。ticket.py result --index N --status placed --broker-id <id from the response> を実行するか、ユーザーが「Deny」を押した場合は --status denied、エラーの場合は --status failed と --note を指定します。新たな確認と新たな yes がない限り、失敗した注文を再試行してはいけません。
6. 約定が確認できたら（ツールの応答、または後で get_all_positions から確認できた場合）、ticket.py fill を実行して、trader-tax 用に trader/portfolio.json へ税務ロットとして追加します。その後、次のチケットに進みます。

例：リール

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

ユーザーが「yes」と回答します。Claude が記録して place_stock_order を呼び出すと、カードにはその JSON と 2 つのボタン（「Allow once」「Deny」）が表示され、「Claude wants to use Place stock order」と記載されます。「Allow once」を選ぶと、注文がペーパー口座に送信されます。

決して行わないこと

• 3 つのゲートすべてを通過せずに注文を発注してはいけません。また、1 回の yes で 2 件の注文を発注してはいけません。
• スケジュール済みタスクやバックグラウンドタスクから注文を発注してはいけません。そこには yes と答える人がいません。
• API キーやパスワードを求めたり、読み取ったり、保存したり、繰り返したりしてはいけません。
• ALPACA_PAPER_TRADE や "paper" を live に切り替えてはいけません。ユーザー自身が切り替えます。
• close_all_positions、cancel_all_orders、オプションや暗号資産の注文ツールを独断で呼び出してはいけません。

安全性

• 教育とツールの提供を目的としており、金融アドバイスではありません。ここでの注文は推奨ではなく、利益を約束するものでもありません。
• デフォルトはペーパートレードです（"paper": true、ALPACA_PAPER_TRADE が true）。live に切り替えるかどうかは、ユーザー自身が決定します。
• このパック内で注文を発注するのは trader-broker のみです。かつ、次の 3 つをすべて満たす場合に限ります。trader-risk がその日のその注文を承認していること、ユーザーがチャットでその注文に対して明示的に yes と入力していること、注文ツールが「Needs approval」に設定されているためユーザーが Claude 自身のカードで「Allow once」をクリックしていること（Customize > Connectors > tool permissions）。注文ツールを「Always allow」に設定してはいけません。
• 設定で許可され、ユーザーが確認しない限り、オプション、証拠金取引、空売り、レバレッジは利用しません。
• ブローカーのキーは環境変数または Claude Desktop の設定に保存し、チャットには決して記載しません。