alpaca-trading-paper-trading-mcp

Name: alpaca-trading-paper-trading-mcp
Author: alpacahq

github.com/alpacahqその他157106 回インストール1 週間前に更新

alpaca-trading-paper-trading-mcp について

Alpacaのペーパートレード口座を使うユーザー向けに、Alpaca Trading API MCP Serverで注文をプレビュー、送信、管理する手順を示すスキルです。戦略の確認、ペーパー環境の検証、送信前の全パラメーター確認を重視します。

主な機能

01MCPツールとパラメーター仕様の検出
02ペーパーモードと口座状態の確認
03戦略確認と注文設定の収集
04株式・暗号資産・オプション注文のプレビュー
05注文状態と約定の確認

活用シーン

01ペーパー口座で取引案を試す
02送信前に注文設定とリスク制御を確認
03約定・拒否・部分約定を追跡
04MCPツールで複数資産クラスの注文を管理

MCP 対応

Alpaca Trading API MCP Serverを通じて取引ツールを呼び出します。GetDynamicToolsで名前空間とツール仕様を検出し、認証とAPI通信はサーバーが処理します。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/alpacahq/alpaca-skills --skill alpaca-trading-paper-trading-mcp

インストール後、Claude Code で/alpaca-trading-paper-trading-mcpを入力して読み込まれたか確認します。

同梱ファイルreference.md

詳細

Alpaca Paper Trading — MCP サーバーバージョン

Alpaca Trading API MCP Server を使用して、ペーパートレードの注文をプレビュー、送信、確認、管理する場合に、このスキルを使用してください。

このスキルは、Alpaca のご自身のペーパートレードアカウントで Trading API を利用する方向けです。エージェントは MCP ツールを直接呼び出すため、CLI のインストールも、生の HTTP リクエストも必要ありません。MCP サーバーが認証と API 通信を処理します。

これは MCP サーバー専用のバージョンです。汎用版（実装に依存しないバージョン）と CLI 版も、関連するスキルとして用意されています。

0 — AI エージェントによるこのスキルの使用方法

シグナルの発生源から始めます。 バックテストの結果、手動の取引アイデア、スケジュールされたトリガー、会話での依頼のいずれに由来する場合でも、取引の判断材料を特定します。
戦略のロジックを言い直し、確認を求めます。 エージェントは取引のアイデアを自分の言葉で言い直し、続行する前にユーザーの確認を待つ必要があります。
すべての設定を収集して確認します。 タイミング、資産クラス、シンボル、売買の別、数量または金額、注文タイプ、執行条件、指値／逆指値価格、時間外取引フラグ、リスク管理設定（ポジション上限、注文の最大サイズ、損失しきい値）、および証拠金の利用意図を確認します。
利用可能な MCP ツールを確認します。 エージェントは GetDynamicTools を呼び出して Alpaca の MCP 名前空間を見つけ、ツールを呼び出す前に利用可能なツールのスキーマを確認する必要があります。ツール名とパラメーターは MCP サーバーの実装によって異なるため、決して推測してはいけません。
ペーパー環境であることを確認します。 ホストの MCP 設定ファイルから env.ALPACA_PAPER_TRADE を読み取ります。この値を公開するツールはありません。値が未設定、true、1、または yes のいずれかであることを必須とします。次に、アカウントが有効で、ブロックされていないことを確認します。ペーパーモードであることを証明できない場合は、直ちに停止してユーザーに伝えます。
注文の全内容をプレビュー表で表示します。 注文送信ツールに渡すすべてのパラメーターを、送信前にユーザーが確認できるようにします。
各注文の前に明示的な確認を求めるかどうかを尋ねます（デフォルト：ON）。セッション中はユーザーの希望に従います。
資産クラスに対応する注文送信ツールを使用します。 注文送信ツールは株式、暗号資産、オプションに分かれています。資産クラスに応じて選択し、確認済みのパラメーターをプレビューどおりに渡します。
注文照会ツールと注文一覧ツールで監視します。 約定、拒否、一部約定、ポートフォリオへの影響を報告します。
ライブ取引は決して行いません。 注文を送信するたびにペーパー環境であることを確認します。

1 — 前提条件

必須

エージェントのホスト（Cursor など）に Alpaca Trading API MCP Server がインストールされ、設定されていること
MCP サーバーの設定で ペーパートレードの API キーとシークレット が環境変数として設定されていること — チャットに貼り付けたり、ツールの引数として渡したりしないでください
GetDynamicTools で MCP サーバーの名前空間を検出できること
Alpaca のペーパートレードアカウントが有効であること

条件付き

オプション取引：Alpaca のペーパートレードアカウントで有効になっている必要があります
暗号資産取引：Alpaca のペーパートレードアカウントで有効になっている必要があります

MCP サーバーのセットアップ（Cursor）

このサーバーは、alpacahq/alpaca-mcp-server で保守されている Alpaca 公式の MCP サーバーです。パッケージ名、コマンド、環境変数については、このリポジトリの README を正として参照してください。以下の設定は v2 に対応しています。

~/.cursor/mcp.json に追加します：

{
  "mcpServers": {
    "alpaca-paper-trading": {
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "your-paper-key",
        "ALPACA_SECRET_KEY": "your-paper-secret",
        "ALPACA_PAPER_TRADE": "true"
      }
    }
  }
}

変数	必須	デフォルト	用途
`ALPACA_API_KEY`	はい	—	ペーパー取引用の API キー
`ALPACA_SECRET_KEY`	はい	—	ペーパー取引用のシークレットキー
`ALPACA_PAPER_TRADE`	いいえ	`true`	ペーパー取引／ライブ取引の切り替え。`false` にするとライブ取引が選択されます。このスキルでは `true` が必要です。
`ALPACA_TOOLSETS`	いいえ	すべて	公開するツールセットをカンマ区切りで指定します。未設定の場合、すべての機能が利用できます。エージェントがアクセスできる範囲を限定する場合にのみ設定してください（例：`account,trading,assets`）。

ペーパー取引かライブ取引かは、ALPACA_PAPER_TRADE のみで決まります。サーバーはこのフラグに基づいて API ホストを設定するため、設定するベース URL の変数はなく、確認する必要もありません。

MCP サーバーが利用可能か確認する

エージェントに次のコマンドを実行させます：

GetDynamicTools with pattern "alpaca"

名前空間が見つからない場合、"error" または "loading" 状態になっている場合、あるいは namespaceStatus: "needsAuth" になっている場合：

"needsAuth" の場合 — その名前空間に対して mcp_auth で認証し、再試行します。
"error" または見つからない場合 — Cursor の設定で MCP サーバー設定を確認するよう伝えます。
直接 HTTP 呼び出しや CLI コマンドへのフォールバックはしないでください。これは MCP 版です。

2 — 入力情報を収集する

入力テーブル

パラメーター	必須	デフォルト	備考
`symbol`	はい	—	ティッカーシンボル（例：`AAPL`、`BTC/USD`、`AAPL251219C00250000`）
`side`	はい	—	`buy` または `sell`
`qty`	qty/notional のいずれか	—	株式数／数量。整数または小数を指定できます。`notional` とは同時に指定できません
`notional`	qty/notional のいずれか	—	金額（ドル）。株式：`day` TIF の成行注文のみ。暗号資産：成行注文のみ。`place_option_order` では利用できません
`type`	いいえ	`market`	株式：`market`、`limit`、`stop`、`stop_limit`、`trailing_stop`。暗号資産：`market`、`limit`、`stop_limit`。オプション：`market`、`limit`。パラメーターは `order_type` ではなく `type` です
`time_in_force`	いいえ	株式は `day`、暗号資産は `gtc`、オプションは `day`	株式：`day`、`gtc`、`opg`、`cls`、`ioc`、`fok`。暗号資産：`gtc` または `ioc` のみ — `day` と `fok` は拒否されます。オプション：`day` のみ
`limit_price`	`limit`／`stop_limit` の場合	—	指値価格
`stop_price`	`stop`／`stop_limit` の場合	—	ストップ発動価格
`trail_percent`	`trailing_stop` の場合	—	トレーリングストップのパーセンテージ。`place_stock_order` のみ
`trail_price`	`trailing_stop` の場合	—	トレーリングストップの金額オフセット。`place_stock_order` のみ
`extended_hours`	いいえ	`false`	時間外取引での約定を許可します。`place_stock_order` のみ。TIF が `day` または `gtc` の `limit` タイプ
`client_order_id`	いいえ	省略した場合、Alpaca が生成	冪等性キー — エージェントが注文ごとに生成します
`order_class`	いいえ	`null`	`simple`、`bracket`、`oco`、`oto`。`place_stock_order` のみ。以下のブラケットレッグ用パラメーターのいずれかが指定されると、自動的に `bracket` に設定されます
`take_profit_limit_price`	ブラケット注文の場合	—	利益確定レッグの指値価格。`place_stock_order` のみ
`stop_loss_stop_price`	ブラケット注文の場合	—	損切りレッグのストップ価格。`place_stock_order` のみ
`stop_loss_limit_price`	いいえ	—	損切りレッグの指値価格。`stop_loss_stop_price` が必要です
`position_intent`	いいえ	—	`buy_to_open`、`buy_to_close`、`sell_to_open`、`sell_to_close`（オプション）

ブラケットレッグは、入れ子になったオブジェクトではなく、フラットなスカラー型パラメーターです。POST /v2/orders では、入れ子になった take_profit: { limit_price } と stop_loss: { stop_price, limit_price } を受け取りますが、place_* ツールではそれらをフラット化しており、スキーマでは additionalProperties: false が設定されています。そのため、入れ子になった REST 形式を渡すと、フィールドが無視されるのではなく、明示的に拒否されます。これは一般的な注意点です。ツールは REST の本文を意図的に組み替えるため、REST スキーマからパラメーターを作成しないでください。

収集する追加コンテキスト

入力	必須	デフォルト	備考
`asset_class`	推定	`us_equity`	`us_equity`、`crypto`、`us_option`
`strategy_description`	推奨	—	取引の根拠を自然言語で記述したもの
`risk_controls`	推奨	—	最大ポジションサイズ、最大損失しきい値、ポートフォリオの集中度上限
`mcp_namespace`	検出	—	Alpaca のツールが利用可能な MCP 名前空間（`GetDynamicTools` 経由）

戦略確認チェックリスト

注文プレビューに進む前に、エージェントは以下を確認する必要があります。

戦略の意図を平易な言葉で言い換えて確認
シンボル、売買方向、数量／金額を確認
注文タイプとすべての価格水準を確認
有効期間を確認
時間外取引の意図を確認（株式）
リスク管理条件を確認（または明示的に免除）
資産クラス固有の要件を確認（オプションの承認、暗号資産の取引資格）
ペーパー取引環境を確認

3 — 信頼できる情報源

情報源	URL	用途
Alpaca MCP Server	https://github.com/alpacahq/alpaca-mcp-server	サーバーのセットアップ、環境変数、ツールセット、最新のツール一覧
Alpaca Trading API docs	https://docs.alpaca.markets/us/docs/trading-api	注文パラメーター、口座フィールド、資産の詳細
Create Order reference	https://docs.alpaca.markets/us/reference/postorder	基盤となる REST の仕様のみ — ツールのパラメーター形式ではありません。`place_*` ツールはこのスキーマをフラット化し、制約を加えているため、パラメーターは必ず検出したツールのスキーマから作成してください
Order types guide	https://docs.alpaca.markets/us/docs/orders-at-alpaca	注文タイプの動作、TIF のルール、時間外取引
Options trading	https://docs.alpaca.markets/us/docs/options-trading	オプション注文の要件、権利行使／割り当て
Crypto trading	https://docs.alpaca.markets/us/docs/crypto-trading	暗号資産の取引ペア、24 時間 365 日の取引、端数単位
Account API	https://docs.alpaca.markets/us/reference/getaccount-1	口座のステータスフィールド、購買力、PDT
Alpaca disclosures	https://alpaca.markets/disclosures	開示文言

検出ルール

ツールを呼び出す前に、エージェントは必ず GetDynamicTools を呼び出して、実際の MCP 名前空間、ツール名、パラメータースキーマを検出しなければなりません。このスキルで挙げている名前は v2 の公式サーバーのものです。名前を確認し、パラメーター形式を決めつけないでください。

4 — ワークフロー

フェーズ 1：戦略の確認

ステップ 1 — シグナルの発生源を特定します。

取引アイデアがどこから来たのかを確認します。

バックテスト結果（実行フォルダーとシグナルを参照）
手動のアイデア（「AAPL を 100 株買いたい」など）
スケジュールまたは条件付きトリガー（「AAPL が 180 ドルを下回ったら買う」など）
ポートフォリオのリバランス（「TSLA のポジションを決済して NVDA に乗り換える」など）

ステップ 2 — 戦略を言い換えて確認します。

エージェントは、取引内容を自分の言葉で言い直します。

「ペーパーカウントで、AAPL を 10 株、当日限りの成行注文で買いたいということですね。これは手動の方向性取引で、ストップロスもテイクプロフィットも設定しません。これでよろしいですか？」

ステップ 3 — 確認を待ちます。

確認を得るまで先に進まないでください。詳細に修正があった場合、エージェントは更新内容を再確認します。

フェーズ 2：設定の合意

ステップ 4 — 上記の入力テーブルから、すべての注文パラメーターを収集します。

ステップ 5 — 指値注文、逆指値注文、またはブラケット注文の場合は、すべての価格水準を確認します。

ステップ 6 — 有効期間と時間外取引の設定を確認します。

ステップ 7 — リスク管理を確認します。

この銘柄の最大ポジションサイズ
1 回の注文における最大想定元本
ポートフォリオの集中度の上限
ストップロスまたはテイクプロフィットの水準（ブラケット注文の場合）

ステップ 8 — オプションの場合は、契約シンボル、ポジションの意図（buy_to_open など）、およびオプション取引が有効になっていることを確認します。

ステップ 9 — 暗号資産の場合は、取引ペア（例：BTC/USD）、数量の精度、24 時間 365 日取引可能であることを確認します。

フェーズ 3：MCP の検出とペーパー口座の確認

ステップ 10 — Alpaca MCP の名前空間を検出します。

Call GetDynamicTools with pattern "alpaca" to find the namespace.
Then call GetDynamicTools with the found namespace to list all available tools.

エージェントは、利用可能なツールとそのパラメータースキーマを調べます。MCP サーバーのバージョンによってツール名やスキーマが変わる可能性があるため、この手順は毎回実行しなければなりません。

ステップ 11 — MCP 経由で口座のステータスを取得します。

口座情報ツール（v2 では get_account_info）を呼び出し、検出結果と名前が一致することを確認します。

応答から以下を確認します。

status = ACTIVE
trading_blocked = false
account_blocked = false

ペーパーモードかどうかはこれらのフィールドではなく、サーバーの ALPACA_PAPER_TRADE 設定によって決まります。

ステップ 12 — 停止ゲート：MCP クライアントの設定からペーパーモードであることを確認し、確認できない場合は停止します。

MCP サーバーは ALPACA_PAPER_TRADE をエージェントに公開しません。この設定値を報告するツール、リソース、サーバー指示のフィールドはないため、エージェントはサーバーにどのモードで動作しているか尋ねられません。この値を読み取れる場所は、クライアント自身の MCP 設定ファイルだけです。このファイルには、同じ env ブロック内に ALPACA_API_KEY と ALPACA_SECRET_KEY も含まれているため、エージェントはファイル全体を読み取ってはいけません。cat、ファイル読み取りツール、サーバーエントリーの表示も禁止です。ファイル全体を読み取ると、認証情報がモデルコンテキストに取り込まれ、§8 のデータ取り扱いに関する保証に違反します。このゲートに必要なのは値が1つだけなので、その値だけを抽出します。

# 1. List server names (names are not secrets)
jq -r '.mcpServers | keys[]' ~/.cursor/mcp.json

# 2. Confirm the chosen entry exists, then read only the flag
jq -r '.mcpServers | has("<server-name>")' ~/.cursor/mcp.json
jq -r '.mcpServers["<server-name>"].env.ALPACA_PAPER_TRADE // "unset"' ~/.cursor/mcp.json

jq がインストールされていないホストでは、同じ値のみを読み取るには次の方法を使います。

python3 -c 'import json,sys;d=json.load(open(sys.argv[1]));e=d["mcpServers"][sys.argv[2]].get("env") or {};print(e.get("ALPACA_PAPER_TRADE","unset"))' ~/.cursor/mcp.json '<server-name>'

ホストが Cursor ではない場合は、そのホスト固有の設定ファイルパスに置き換えてください。その後、エージェントは次の手順を実行します。

検出した Alpaca ツールの名前空間を提供するサーバーエントリーを特定し、そのエントリーが存在することを確認します。上記のステップ2を参照してください。
フラグが unset であるか、true、1、yes のいずれかに設定されていることを必須とします（大文字と小文字は区別しません）。サーバーは値を小文字に変換して、この集合に完全一致するかを判定するため、それ以外の値はすべてライブモードを選択します。paper、末尾に空白がある TRUE 、yes! も該当します。

読み取り結果が空になる2つのケースは同じではないため、区別してください。エントリーが存在すると確認でき、そのフラグが unset である場合は合格です。変数が存在しない場合、サーバーはデフォルトでペーパーモードになります。一方、エントリーが見つからない場合や設定を解析できない場合は、判定不能であり、合格ではありません。表示される値は、フラグが本当に存在しない場合と区別できません。後者のケースを前者として扱ってはいけません。

設定を読み取れない、または解析できない場合、サーバーエントリーを特定できない場合、あるいは値がこの集合に含まれない場合、ゲートはフェイルクローズします。エージェントは処理を停止し、次のように伝えます。

"⚠️ この MCP サーバーがペーパーモードであることを確認できません。このスキルはペーパートレーディングのみをサポートします。サーバーの env ブロックで ALPACA_PAPER_TRADE が true になっていること、および設定済みのキーがペーパー用であることを確認してから、クライアントを再起動してください。"

エージェントは、アカウントレスポンスを証拠として扱ってはいけません。ライブアカウントとペーパーアカウントは同じ形式で返されるため、アカウントのペイロードだけでは環境を特定できません。証明できない場合はライブとして扱ってください。より弱いシグナルが2つあり、合格した設定チェックの裏付けにはなりますが、代わりにはなりません。ペーパーアカウントでは、account_number が PA で始まることがよくあり、status が PAPER_ONLY である場合もあります。どちらも文書化された保証ではありません。

ペーパーモードが確認できない場合は、いかなる状況でも処理を続行しないでください。

ステップ13 — アカウントレスポンスから、次の項目を確認します。

buying_power — 予定注文に十分な額であること
options_trading_level — オプションを取引する場合。これは有効なレベル（options_approved_level と設定済みの max_options_trading_level の低い方）なので、options_approved_level ではなくこちらを基準に判定します
options_buying_power — オプションを取引する場合
crypto_status — 暗号資産を取引する場合
multiplier — 証拠金区分、およびアカウントオブジェクトに含まれる唯一の PDT シグナルです。4 は PDT アカウントを意味します

アカウントオブジェクトには、pattern_day_trader、daytrade_count、daytrading_buying_power の各フィールドはありません。エージェントはこれらを読み取ってはいけません。

ステップ14 — アカウントの概要を表示します。

┌─────────────────────────────────────────┐
│         Paper Account Summary           │
├─────────────────────┬───────────────────┤
│ Account ID          │ xxxxxxxx          │
│ Status              │ ACTIVE            │
│ Environment         │ PAPER             │
│ Equity              │ $100,000.00       │
│ Buying Power        │ $200,000.00       │
│ Cash                │ $100,000.00       │
│ Options Approved    │ Level 2           │
│ Crypto Status       │ ACTIVE            │
│ PDT                 │ No                │
└─────────────────────┴───────────────────┘

フェーズ4：注文のプレビュー

ステップ15 — 注文パラメーターオブジェクトを作成します。送信ツールはまだ呼び出さないでください。

ステップ19で選択した注文発注ツールに送信する、正確なパラメーター一式を作成します。

{
  "symbol": "AAPL",
  "side": "buy",
  "qty": "10",
  "type": "limit",
  "limit_price": "185.50",
  "time_in_force": "day",
  "client_order_id": "pt-20260726-001-aapl-buy"
}

ステップ16 — 注文のプレビューを表示します。

┌─────────────────────────────────────────┐
│           ORDER PREVIEW                 │
├─────────────────────┬───────────────────┤
│ Symbol              │ AAPL              │
│ Side                │ BUY               │
│ Quantity            │ 10 shares         │
│ Order Type          │ LIMIT             │
│ Limit Price         │ $185.50           │
│ Time in Force       │ DAY               │
│ Extended Hours      │ No                │
│ Order Class         │ Simple            │
│ Est. Notional       │ $1,855.00         │
│ Client Order ID     │ pt-20260726-...   │
│ Environment         │ PAPER (verified)  │
├─────────────────────┴───────────────────┤
│ ⚠ Paper trading only. Not financial    │
│   advice. Past performance ≠ future.   │
└─────────────────────────────────────────┘

ステップ17 — 確認がON（デフォルト）の場合は、送信する前に、明示的な「yes」または「go ahead」の応答を待ちます。

ステップ18 — 以前に確認をOFFに設定している場合は、プレビューを表示して内容を読む時間を少し設けてから、続行します。

フェーズ 5：MCP を介した注文の送信

ステップ 19 — 資産クラスに対応する注文発注ツールを選択し、呼び出します。

注文作成用のツールは 1 つではありません。注文発注は資産クラスごとに分かれているため、ステップ 7 で確認した資産クラスに基づいてツールを選択します。

資産クラス	ツール（v2 時点）	対応する注文タイプ
米国株式／ETF	`place_stock_order`	成行、指値、逆指値、逆指値付き指値、トレーリングストップ、ブラケット
暗号資産	`place_crypto_order`	成行、指値、逆指値付き指値
米国オプション	`place_option_order`	単一レッグおよびマルチレッグ

各ツールには固有のスキーマがあります。株式で使用できる注文タイプがすべて暗号資産で使用できるわけではないため、別のツールのパラメーターを再利用せず、選択したツールのスキーマを確認してください。呼び出す前に、ディスカバリー情報で名前とパラメーターを確認してください。上記の名前は v2 時点のものであり、バージョンをまたいで保証されるものではありません。

Call place_stock_order with:
  symbol: "AAPL"
  side: "buy"
  qty: "10"
  type: "limit"
  limit_price: "185.50"
  time_in_force: "day"
  client_order_id: "pt-20260726-001-aapl-buy"

ステップ 20 — レスポンスを解析します。

MCP のレスポンスから、以下を抽出します。

id — Alpaca の注文 ID
client_order_id — 冪等性キー
status — 注文の初期ステータス（new、accepted、pending_new）
created_at — 送信日時
filled_qty、filled_avg_price — 即時に約定した場合（成行注文）

ステップ 21 — 失敗した場合：

MCP ツールの呼び出しでエラーが返された場合：

エラーの種類	対応
購買余力不足	現在の購買余力を表示し、数量を減らすか指値注文を使用するよう提案します
無効なシンボル	資産検索ツール（v2 時点では `get_asset`）でシンボルを確認し、修正候補を提案します
無効なパラメーター	検証に失敗したパラメーターを示し、正しいスキーマを参照します
市場が休場（`day` TIF の場合）	時計ツールで取引時間を表示し、`gtc` を指定するか、取引開始まで待つよう提案します
オプション取引が有効になっていない	Alpaca のダッシュボードでオプション取引を有効にするよう伝えます
口座の取引制限	制限の理由を表示し、Alpaca サポートへの問い合わせを提案します
MCP ツールエラー	生のエラーを表示し、MCP サーバーのログを確認するよう提案します

失敗した試行は、ステータスを FAILED、エラーメッセージを記録したうえで order_log.csv に記録します。

フェーズ 6：MCP を介した送信後のモニタリング

ステップ 22 — 注文ステータスを確認します。

単一注文の照会ツール（v2 時点では get_order_by_id）を、ステップ 20 の注文 ID とともに呼び出します。送信結果が不明確で注文 ID がない場合は、代わりに冪等性キーを使って注文を照会します（get_order_by_client_id を使用）。

現在のステータスと約定情報を報告します。

ステップ 23 — すべての未決注文を一覧表示します（求められた場合、または参考情報として有用な場合）。

注文一覧ツール（v2 時点では get_orders）を、未決注文に絞り込んで呼び出します。

すべての未決注文の概要表を表示します。

ステップ 24 — 注文の概要を返します。

┌─────────────────────────────────────────┐
│           ORDER SUBMITTED               │
├─────────────────────┬───────────────────┤
│ Order ID            │ abc-123-def       │
│ Symbol              │ AAPL              │
│ Side                │ BUY               │
│ Qty                 │ 10                │
│ Type                │ LIMIT @ $185.50   │
│ Status              │ NEW               │
│ Submitted           │ 2026-07-26 15:30  │
│ Environment         │ PAPER (verified)  │
├─────────────────────┴───────────────────┤
│ Next: Check status, modify, or cancel.  │
└─────────────────────────────────────────┘

ステップ 25 — 注文ライフサイクルを報告します。

注文の進行に応じて、エージェントは状態の遷移を報告します。

ステータス	報告内容
`new` / `accepted`	注文は有効で、約定待ちです
`partially_filled`	約定数量、残数量、平均約定価格を表示します
`filled`	約定総数量、平均約定価格、推定コストを表示します
`canceled`	キャンセルを確認し、約定済みの部分があれば表示します
`expired`	期限切れ（TIF の期間終了）を伝え、適切であれば再送信を提案します
`rejected`	拒否理由を表示し、対処方法を提案します
`replaced`	変更前と変更後の注文詳細を表示します

全約定または一部約定した注文について、ポートフォリオへの影響を計算します。

新しいポジションサイズ（または既存ポジションの変動）
推定取得原価
残りの購買余力
このポジションのポートフォリオに占める比率

フェーズ 7：MCP によるポートフォリオへの影響

ステップ 26 — すべてのポジションを取得します。

すべてのポジションを取得するツール（v2 時点の get_all_positions）を呼び出します。

ポジションの概要を表にして表示します。

ステップ 27 — 特定のポジションを取得します（単一のシンボルを確認する場合）。

対象のシンボルについて、単一ポジションを取得するツール（v2 時点の get_open_position）を呼び出します。

ポジションの詳細（数量、平均取得価格、現在価格、未実現損益、時価）を表示します。

ステップ 28 — 更新後の口座情報を取得します。

口座情報を取得するツール（v2 時点の get_account_info）をもう一度呼び出します。

取引後の更新された純資産、購買余力、現金を表示します。

ステップ 29 — ポートフォリオのリスク概要：

┌─────────────────────────────────────────────┐
│         Portfolio Risk Summary              │
├──────────────────┬──────────────────────────┤
│ Total Equity     │ $99,850.00              │
│ Cash             │ $98,000.00              │
│ Market Value     │ $1,855.00               │
│ Buying Power     │ $196,000.00             │
│ Positions        │ 1                       │
│ Largest Position │ AAPL (100% of invested) │
│ Unrealized P&L   │ +$5.00 (+0.27%)         │
│ Day P&L          │ +$5.00                  │
└──────────────────┴──────────────────────────┘

フェーズ 8：MCP による注文管理

ステップ 30 — 特定の注文をキャンセルします。

単一注文のキャンセルツール（v2 時点の cancel_order_by_id）を、注文 ID を指定して呼び出します。

キャンセルを確認します。注：約定済みの注文はキャンセルできません。

ステップ 31 — すべての未約定注文をキャンセルします。

一括キャンセルツール（v2 時点の cancel_all_orders）を呼び出します。このツールは口座内のすべての未約定注文に一度に作用するため、確認モードが OFF の場合でも、対象となる注文の一覧を表示して、呼び出す前に確認を得てください。

キャンセルされた注文の数を確認します。キャンセルできなかった注文（すでに約定済み、または約定処理中）も表示します。

ステップ 32 — 既存の注文を置き換えます（変更します）。

置き換えツール（v2 時点の replace_order_by_id）を、注文 ID と変更するフィールドのみを指定して呼び出します。

変更前と変更後の比較表を表示します。置き換え可能なのは、未約定または一部約定した注文のみです。

ステップ 33 — 単一のポジションを決済します。

単一ポジションの決済ツール（v2 時点の close_position）を呼び出します。このツールでは symbol_or_asset_id（必須）と、任意で qty または percentage のどちらかを指定します。これらのパラメーターは同時に指定できません。どちらも省略すると、ポジション全体を決済します。

これはキャンセルではありません。ポジションに対する成行売り注文を送信するため、実際の（ペーパートレードの）資金が動き、市場の取引時間の影響を受けます。市場が閉まっている場合、注文はキューに入り、次の市場開始時に執行されます。そのため、承認時点では約定価格が不明です。市場が閉まっているとき、エージェントはポジションがすでにゼロになったかのように示唆せず、このことを明示します。

エージェントは決済しようとしているポジション（シンボル、数量、時価、未実現損益）を表示し、明示的な確認を求めます。確認モードは注文の発注に適用され、これは注文の発注にあたるため、設定が OFF でも清算の確認は省略されません。呼び出し後、結果の注文 ID を報告し、他の注文と同じように終端状態まで監視します。

ステップ 34 — すべてのポジションを決済します。

一括決済ツール（v2 時点の close_all_positions）を呼び出します。このツールの唯一のパラメーターである cancel_orders を true に設定すると、清算前にすべての未約定注文をキャンセルします。

これはこのスキルで最も破壊的な操作です。このセッションで開いていないポジションも含めてポートフォリオ全体を清算し、cancel_orders: true を指定すると、未約定注文も取り消します。エージェントはまず、影響を受ける資産の全一覧を表示します。

ポジション一覧ツールから取得したすべての未決済ポジション（シンボル、数量、時価、未実現損益を含む）
清算対象となる時価の合計
cancel_orders: true を指定する場合、その指定によってキャンセルされるすべての未約定注文

次に対象件数を伝え、confirmation_mode の設定にかかわらず、必ず明示的な「はい」を求めます。その後にのみツールを呼び出します。呼び出し後は、決済されたポジションの数を報告し、失敗したポジションがあれば提示します。一部失敗するとポートフォリオが不完全に清算された状態になるため、そのことを把握する必要があります。

ステップ 35 — オプションの権利行使。

権利行使は取り消せず、原資産の受け渡しにつながるため、exercise_options_position と do_not_exercise_options_position（いずれも v2 時点）には、ステップ 34 と同じ明示的な確認要件が適用されます。エージェントはどちらかを呼び出す前に、契約内容、発生する原資産の義務、現金への影響を表示し、独自の判断で権利行使を指示することはありません。

フェーズ 9：デプロイに関するガイダンス（依頼があった場合）

対話セッション以外でこれらの取引を自動化する方法について尋ねた場合：

MCP ベースの自動化

MCP サーバーはセッションベースであり、通常は Cursor などのエージェントホスト内で実行されます
MCP ベースの取引を定期的に行う場合は、Cursor の自動化機能や、スケジュール設定されたエージェントのトリガーを検討してください
各セッションで MCP サーバーが実行され、認証済みである必要があります

スタンドアロンの自動化

本番環境向けの自動化には、Alpaca SDK を直接使用してください：
- Python：alpaca-py（pip install alpaca-py）
- TypeScript/JavaScript：@alpacahq/alpaca-trade-api または @alpacahq/typescript-sdk
スケジュール設定された戦略には、cron と SDK スクリプトを使用します
イベント駆動型の取引には、クラウド関数（AWS Lambda、GCP Cloud Functions）を使用します
TradingView やカスタムのシグナルプロバイダーからの Webhook ベースのトリガーを使用します

スタンドアロンの自動化では、このスキルの保証は適用されません。ステップ 12 のペーパー取引ゲートが対象とするのは、対話セッション内の MCP ツール呼び出しです。cron、クラウド関数、Webhook で実行する SDK スクリプトには MCP サーバーもゲートもありません。スクリプトは起動時に自らペーパー環境であることを確認し、それが確認できなければ終了する必要があります。エンドポイントを設定から読み込むのではなく、paper=True をリテラルとして指定してクライアントを作成し、環境にライブエンドポイントまたはライブ取引フラグが存在する場合は中断してください。ライブ口座はペーパー口座と同じ形式の応答を返すため、実行中に後続の処理でこのエラーが明らかになることはありません。

必ず：

ライブ取引を検討する前に、新しい自動化を十分な期間ペーパー環境で検証します
サーキットブレーカー（1 日あたりの最大損失、1 日あたりの最大注文数、最大ポジションサイズ）を実装します
すべての注文を記録し、予期しない動作がないか監視します
エージェントは、特定のクラウドプロバイダーやインフラの選択を推奨しません

5 — 執行ルール

共通ルール

ペーパー取引のみ。 このスキルはペーパー取引専用です。エージェントは注文を送信するたびに、ペーパー環境であることを確認する必要があります。
金融アドバイスは行いません。 エージェントは、あなたの指示に従って取引を執行します。取引の推奨、価格予測、戦略の提案は行いません。
デフォルトで確認を求めます。 オプトアウトしない限り、エージェントは注文ごとに明示的な確認を求めます。
冪等性。 再試行時の重複送信を防ぐため、すべての注文に一意の client_order_id を付与します。
完全な透明性。 MCP ツールに送信するすべてのパラメーターが、プレビューに表示されます。
安全側に停止します。 確認手順（口座確認、ペーパー環境の検証、購買余力）のいずれかに失敗した場合、エージェントは停止して理由を説明します。
補間しません。 エージェントは、あなたが確認したパラメーターをそのまま使用します。「おそらくこういう意味だろう」と推測して値を黙って変更することはありません。
制限を開示します。 MCP サーバーが依頼された機能（特定の注文タイプなど）に対応していない場合、エージェントは回避策を試すのではなく、その旨を伝えます。
対象範囲の指定がない破壊的なツールにはゲートを設けます。 cancel_all_orders、close_all_positions、close_position、exercise_options_position、do_not_exercise_options_position は、このセッションで作成されたとは限らない保有資産に対して動作し、後ろの 3 つは取り消せません。エージェントは、各呼び出しの影響範囲を正確に一覧表示し、注文の発注のみを対象とする confirmation_mode の設定にかかわらず、明示的な確認を求めます。
ポジションの決済は注文の発注です。 決済ツールはポジションを削除するのではなく、成行売り注文を送信します。これらのツールは市場時間に従い、市場が閉まっている場合は次の市場開始時刻まで注文をキューに入れ、約定価格は不明です。呼び出しが返された時点でポジションがゼロになったと報告するのではなく、エージェントは結果の注文が最終状態に達するまで監視します。

MCP 固有のルール

必ず最初にツールを検出してください。 GetDynamicTools を呼び出して Alpaca 名前空間を確認し、ツールを呼び出す前にツールスキーマを調べてください。このスキルで記載されているツール名は v2 時点のものであり、ドキュメント上の情報であって、保証されたものではありません。v2 は書き直されており、v1 のツールは一つも引き継がれていません。また、名前がバージョン間で同じでも、スキーマが変更されている場合があります。検出結果と照合し、パラメータスキーマをハードコードしないでください。
名前空間の状態に対処してください。 MCP 名前空間が "needsAuth" の場合は、mcp_auth で認証してください。"error" または見つからない場合は、MCP サーバーの設定を確認するよう伝えてください。
生の HTTP へのフォールバックは禁止です。 これは MCP 版です。MCP サーバーが利用可能で正常に動作している場合、直接 HTTP API 呼び出しや CLI コマンドにはフォールバックしないでください。これは、エージェントが Alpaca に接続する方法を定めるものです。Step 12 のペーパー環境確認のためにローカルの MCP 設定を読み取ることは禁止していません。この確認では Alpaca のエンドポイントにアクセスしません。
認証エラーは別の認証情報で再試行できません。 MCP ツールの呼び出しで認証エラーが発生した場合は、MCP サーバーの設定を確認するよう伝えてください。別の認証情報で再試行したり、API キーをツールの引数として渡したりしないでください。
MCP ツールの呼び出しに required_permissions: ["all"] は不要です。 シェルではなく、MCP プロトコル経由で実行されます。
MCP サーバーの境界を尊重してください。 検出されたスキーマに想定していたパラメータ（オプションの position_intent など）が含まれていない場合、捏造せず、その旨を伝え、回避策について API ドキュメントを参照してください。
エラー時は再検出してください。 MCP ツールの呼び出しで予期しないスキーマエラーが発生した場合は、サーバーが更新されている可能性があるため、GetDynamicTools でツールを再検出してください。

資産クラス固有のルール

株式 — 発注前に、資産検索ツールでシンボルの存在と取引可能性を確認してください。株式分割、取引停止、上場廃止がないか確認してください。
オプション — オプションの承認レベルを確認してください。手作業で作成した OCC シンボル（例：AAPL251219C00250000）を信用せず、オプション契約ツールで契約を特定してください。position_intent を確認してください。
暗号資産 — スラッシュ区切りのペア形式（例：BTC/USD）を使用してください。24 時間 365 日取引可能であることに留意してください。端数数量が一般的なため、精度を確認してください。

6 — 出力仕様

実行フォルダーの構成

runs/<YYYYMMDD-HHMMSS>-paper-trading-mcp/
  notes.md              # Strategy description, assumptions, risk controls
  orders.json           # All MCP order responses (create, get, list)
  order_log.csv         # Chronological log of all order actions
  positions_snapshot.json  # Position state after trades
  portfolio_summary.md  # Account and portfolio state
  review.md             # Session review and lessons learned

notes.md

以下を含みます：

戦略の説明と根拠
確認済みのすべてのパラメータ
適用中のリスク管理策
ペーパー環境の確認詳細
行った仮定
タイムスタンプ

orders.json

セッション中に記録された、すべての注文関連 MCP 応答の配列：

[
  {
    "action": "create",
    "timestamp": "2026-07-26T19:30:00Z",
    "request": {
      "symbol": "AAPL",
      "side": "buy",
      "qty": "10",
      "type": "limit",
      "limit_price": "185.50",
      "time_in_force": "day"
    },
    "response": {
      "id": "abc-123-def",
      "status": "new",
      "filled_qty": "0",
      "created_at": "2026-07-26T19:30:01Z"
    }
  }
]

order_log.csv

timestamp,action,order_id,client_order_id,symbol,side,qty,type,limit_price,stop_price,tif,status,filled_qty,filled_avg_price,error
2026-07-26T19:30:00Z,CREATE,abc-123-def,pt-20260726-001,AAPL,buy,10,limit,185.50,,day,new,0,,
2026-07-26T19:31:00Z,STATUS,abc-123-def,pt-20260726-001,AAPL,buy,10,limit,185.50,,day,filled,10,185.48,

positions_snapshot.json

すべての取引完了後に、ポジション一覧 MCP 応答から取得した内容です。

portfolio_summary.md

セッション後の口座状況、ポジション、リスク指標を人が読みやすくまとめたものです。

review.md

セッション後のレビューです。取引内容、結果、教訓、次に行うことを記載します。

注：CLI の出力とは異なり、MCP 応答は生ファイルとして自動的に保存されません。エージェントは、関連する応答データを取得し、orders.json と order_log.csv に明示的に書き込む必要があります。

7 — 検証とテスト

送信前のチェック

エージェントは、注文を送信する前に毎回、次のチェックを行います。

チェック	方法	失敗時の対応
ペーパー環境	ホストの MCP 設定にある `env.ALPACA_PAPER_TRADE` が未設定、`true`、`1`、または `yes` であること。どのツールからも読み取れないため、設定ファイルを読み取ります。読み取れない場合は安全側に倒して処理を中止します	STOP — 再設定するよう案内します
アカウントが有効	`status == "ACTIVE"`	STOP — アカウントの問題を報告します
取引がブロックされていない	`trading_blocked == false`	STOP — アカウントに制限があることを報告します
十分な購買余力	`buying_power >= est_notional`	STOP — 購買余力を表示し、注文数量を減らすよう提案します
シンボルが取引可能	Get-asset ツール	STOP — シンボルが見つからないか、取引できないことを報告します
オプション取引が承認済み	アカウントのオプションレベル	STOP — オプション取引を有効にするよう案内します
暗号資産取引が有効	アカウントの暗号資産ステータス	STOP — 暗号資産取引を有効にするよう案内します
有効な注文タイプ	スキーマ検証	STOP — 有効な注文タイプを表示します
有効な TIF	スキーマ検証	STOP — 有効な TIF オプションを表示します
価格レベルが指定されている	指値注文または逆指値注文では指値価格／逆指値価格を確認	STOP — 不足している価格を確認します
クライアント注文 ID	UUID を生成	不足している場合は生成します

送信後のチェック

チェック	方法	失敗時の対応
注文が受け付けられた	応答ステータス	拒否理由を報告します
重複がない	client_order_id の一意性	重複を検出した場合は警告します
約定が想定の範囲内	filled_avg_price と limit_price を比較	想定外の場合は通知します

MCP 固有の検証テスト

以下の MCP 固有の障害モードを検証します。

MCP 名前空間が見つからない
MCP 名前空間で認証が必要
MCP ツールのスキーマ変更
MCP サーバーが本番環境向けに設定されている
MCP ツール呼び出し時のネットワークエラー

8 — 開示、安全性、データの取り扱い

開示事項

エージェントは、次の開示事項を含める必要があります。

注文をプレビューする前に毎回：

「ペーパートレードのみです。金融アドバイスではありません。過去の実績は将来の結果を保証するものではありません。」
戦略の実績について話す場合：

「ペーパートレードの結果はシミュレーションであり、実際の約定、スリッページ、市場への影響を反映しない場合があります。」
オプションについて話す場合：

「オプションには重大なリスクが伴い、すべての投資家に適しているわけではありません。ペーパートレードでのオプション取引に金銭的リスクは伴いませんが、検証した戦略を実際の取引に適用する場合は、相当なリスクを伴う可能性があります。」
すべての開示事項。 Alpaca の開示事項と契約を alpaca.markets/disclosures で確認してください。

重要な開示事項： この資料は、情報提供、教育、調査のみを目的としています。投資アドバイス、推奨、証券、オプション、暗号資産、その他の金融商品の売買の申し出、または勧誘ではありません。すべての投資および取引には、元本を失う可能性を含むリスクが伴います。ペーパートレードはシミュレーションであり、約定、市場への影響、流動性、手数料、レイテンシなどの点で実際の取引とは異なる場合があります。Alpaca の開示事項を https://alpaca.markets/disclosures で確認してください。

安全性

実際の取引は絶対に行わないでください。 このスキルではペーパー環境かどうかを確認しますが、MCP サーバーの設定は最終的にユーザーの責任です。
API キーを絶対に公開しないでください。 キーは MCP サーバー環境で設定し、エージェント経由では渡しません。
金融アドバイスは絶対に提供しないでください。 エージェントはユーザーの指示に従って注文を実行し、事実を報告します。取引を推奨することはありません。
サーキットブレーカーに注意してください。 短時間に多くの注文を送信した場合、エージェントはそのペースについて指摘し、意図的かどうかを確認してください。
破壊的なツールは、確認モードとは別に制限されています。 注文ごとの確認をオフにすると、注文の発行が速くなります。ただし、close_all_positions、cancel_all_orders、close_position、オプションの権利行使指示では、明示的な「はい」が必須です。
デフォルトでは、ツールセット全体が有効です。 ALPACA_TOOLSETS はすべての機能をデフォルトとするため、清算ツールや権利行使ツールは、デフォルトのインストールであればどれでも利用できます。ゲートだけに頼るのではなく、エージェントから完全にアクセスできないようにする場合は、この変数の範囲を指定してください。

データの取り扱い

MCP ツールの呼び出しは、MCP プロトコルを介して Alpaca API に送信されます。認証情報はサーバーの設定に保存され、ツールの引数として渡されることはないため、ツールの呼び出しによって認証情報がエージェントのコンテキストに含まれることはありません。
エージェントが認証情報を保持するファイルに触れるのは、Step 12 のペーパーゲートだけです。ファイルから読み取るのは単一のフィールドだけとし、ファイル全体やサーバーエントリー全体を読み取ったり、表示したり、エコーしたりしてはいけません。エージェントがそのフィールドだけを抽出できない場合は、ファイル全体を読み取って代替するのではなく、ゲートを失敗させてください。
注文データは実行フォルダー構造にローカル保存されます（§6 を参照）。
Alpaca 以外のサードパーティサービスに取引データが送信されることはありません。
エージェントの会話コンテキストに注文の詳細が含まれる場合があります。チャット履歴は適切に取り扱ってください。

9 — アンチパターン

このスキルに記載されたツールを呼び出す前に、必ずディスカバリーで確認してください。 記載されている名前は v2 向けのものであり、保証されていません。
GetDynamicTools を使ってスキーマを確認する前に、MCP ツールを呼び出してはいけません。
MCP サーバーがペーパー環境用に設定されていると思い込んではいけません。また、アカウントの応答をその証拠として扱ってはいけません。 ペーパーモードは ALPACA_PAPER_TRADE によって決まります。
そのフラグを確認するために、MCP 設定ファイル全体を読み取ってはいけません。 同じ env ブロックに API キーが含まれています。単一のフィールドを抽出してください。
識別できないサーバーエントリーを、フラグが存在しないものとして扱ってはいけません。 フラグが存在しない場合は合格ですが、判定不能の場合は安全側に倒して失敗としてください。
MCP サーバーが利用できる場合、直接 HTTP 呼び出しに切り替えてはいけません。 これは MCP 版です。
API キーを MCP ツールの引数として渡してはいけません。 認証はサーバーが内部で処理します。
実際の取引を行ったり、アカウントが実取引用と思われる場合に処理を続けたりしてはいけません。
プレビューを先に提示せずに注文を送信してはいけません。
ペーパー環境の確認手順を省略してはいけません。
金融アドバイス、価格予測、取引の推奨をしてはいけません。
認証エラーが発生しても、別の認証情報で再試行してはいけません。MCP サーバーの設定を修正するよう伝えてください。
確認後に注文パラメーターを黙って変更してはいけません。
特定の MCP サーバーのパッケージ名やバージョンを決めつけてはいけません。実行時に検出してください。
MCP ツールの呼び出しに required_permissions: ["all"] を使用してはいけません。必要ありません。
検出されたスキーマにない MCP ツールのパラメーターを作り出してはいけません。
一部約定を全量約定として扱ってはいけません。必ず残数量を報告してください。
close_all_positions や cancel_all_orders をユーザーの指示なしに呼び出してはいけません。どちらも対象を限定せず、今セッションで作成したものではない保有資産にも影響します。影響を受ける対象を一覧表示し、明示的な「はい」を求めてください。
明示的な確認なしにオプションの権利行使をしてはいけません。権利行使と権利行使しない旨の指示は、いずれも取り消せません。
クローズツールの応答が返った時点で、ポジションがクローズしてゼロになったと報告してはいけません。売り注文が送信されるだけで、まだキューに入っている場合や、一部約定の場合があります。

10 — 関連ファイル

reference.md — MCP ツールの検出パターン、注文タイプのリファレンス、エラー処理、資産クラス固有の情報

基本情報

作者: alpacahq
リポジトリ: alpacahq/alpaca-skills
カテゴリ: その他
インストール数: 106
GitHub スター: 157

問題を報告