🚀 Alpaca MCP Server
このプロジェクトは、Alpacaの取引API用のモデルコンテキストプロトコル(MCP)サーバーの実装です。Claude Desktop、Cursor、またはVScode上の大規模言語モデル(LLM)が、自然言語(英語)を使用してAlpacaの取引インフラストラクチャとやり取りできるようになります。このサーバーは、株式取引、オプション取引、ポートフォリオ管理、ウォッチリスト管理、およびリアルタイムの市場データアクセスをサポートしています。
✨ 主な機能
- 市場データ
- 株式のリアルタイムの相場、取引、価格バー
- 過去の価格データと取引履歴
- オプション契約の相場とギリシャ文字(スナップショット経由)
- アカウント管理
- 残高、購入力、およびアカウントのステータスを表示
- すべてのオープンおよびクローズされたポジションを確認
- ポジション管理
- 個々の保有資産の詳細情報を取得
- 株数またはパーセンテージですべてまたは一部のポジションを清算
- 注文管理
- 株式およびオプションの注文を入力(成行または指値)
- 個別または一括で注文をキャンセル
- 完全な注文履歴を取得
- オプション取引
- 満期日または行使価格でオプション契約を検索および表示
- マルチレッグのオプション戦略を実行
- 契約の最新の相場とギリシャ文字を取得
- 市場ステータスと企業アクション
- 市場が開いているかどうかを確認
- 市場カレンダーと取引セッションを取得
- 今後の企業発表(収益、株式分割、配当)を表示
- ウォッチリスト管理
- 個人用のウォッチリストを作成、更新、および表示
- 資産を追跡するための複数のウォッチリストを管理
- 資産検索
- 株式およびその他のAlpacaがサポートする資産の詳細を照会
📦 インストール
前提条件
- Python 3.10以上
- Githubアカウント
- Alpaca APIキー(ペーパー取引または実際の取引アクセス)
- Claude for Desktopまたは互換性のあるMCPクライアント
インストール手順
- リポジトリをクローンし、リポジトリディレクトリに移動します。
git clone https://github.com/alpacahq/alpaca-mcp-server.git
cd alpaca-mcp-server
- 仮想環境を作成し、アクティブ化します。
python3 -m venv venv
source venv/bin/activate
注意: 仮想環境は、作成に使用したPythonバージョンを使用します。Python 3.10以上でコマンドを実行すると、仮想環境もPython 3.10以上を使用します。バージョンを確認するには、仮想環境をアクティブ化した後にpython3 --version
を実行できます。
- 必要なパッケージをインストールします。
pip install -r requirements.txt
📚 ドキュメント
プロジェクト構造
クローンして仮想環境をアクティブ化した後、ディレクトリ構造は次のようになります。
alpaca-mcp-server/ ← これがワークスペースフォルダ(= プロジェクトルート)です
├── alpaca_mcp_server.py ← スクリプトはワークスペースルートに直接あります
├── .vscode/ ← VS Codeの設定(VS Codeユーザー向け)
│ └── mcp.json
├── venv/ ← 仮想環境フォルダ
│ └── bin/python
├── .env.example ← 環境テンプレート(.envファイルを作成するために使用)
├── .gitignore
├── Dockerfile ← Dockerの設定(Dockerを使用する場合)
├── .dockerignore ← Dockerの無視設定(Dockerを使用する場合)
├── requirements.txt
└── README.md
.envファイルの作成と編集
プロジェクトディレクトリに資格情報用の.envファイルを作成し、編集します。
ALPACA_API_KEY = "your_alpaca_api_key"
ALPACA_SECRET_KEY = "your_alpaca_secret_key"
PAPER = True
TRADE_API_URL = None
TRDE_API_WSS = None
DATA_API_URL = None
STREAM_DATA_WSS = None
Claude Desktopの使用方法
公式のClaude Desktopのセットアップドキュメントはこちらにあります: https://modelcontextprotocol.io/quickstart/user
MCPサーバーの起動
プロジェクトのルートディレクトリでターミナルを開き、次のコマンドを実行します。
python alpaca_mcp_server.py
Claude for Desktopの設定
- Claude Desktopを開きます。
Settings → Developer → Edit Config
に移動します。
claude_desktop_config.json
を更新します。
注意:
<project_root>
を、クローンしたalpaca-mcp-serverディレクトリへのパスに置き換えてください。これは、ターミナルでpython3 -m venv venv
を使用して作成した仮想環境内のPython実行ファイルを指す必要があります。
{
"mcpServers": {
"alpaca": {
"command": "<project_root>/venv/bin/python",
"args": [
"/path/to/alpaca-mcp-server/alpaca_mcp_server.py"
],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key_for_paper_account",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key_for_paper_account"
}
}
}
}
VS Codeの使用方法
VS Codeは、GitHub Copilotのエージェントモードを通じてMCPサーバーをサポートしています。
公式のVS Codeのセットアップドキュメントはこちらにあります: https://code.visualstudio.com/docs/copilot/chat/mcp-servers
前提条件
- GitHub Copilot拡張機能がインストールされ、アクティブなサブスクリプションを持つVS Code
- Python 3.10以上と仮想環境のセットアップ(上記のインストール手順に従う)
- VS CodeでMCPサポートを有効にする(以下を参照)
1. VS CodeでMCPサポートを有効にする
- VS Codeの設定(Ctrl/Cmd + ,)を開きます。
- "chat.mcp.enabled"を検索し、チェックボックスをオンにしてMCPサポートを有効にします。
- "github.copilot.chat.experimental.mcp"を検索し、チェックボックスをオンにして命令ファイルを使用します。
2. MCPサーバーの設定
推奨: ユーザー全体の設定ではなく、ワークスペース固有の設定(.vscode/mcp.json
)を使用してください。これにより、異なるプロジェクトで異なるAPIキー(複数のペーパーアカウントまたは実際の取引)を使用でき、取引ツールを他の開発作業から分離できます。
ワークスペース固有の設定の場合:
- プロジェクトルートに
.vscode/mcp.json
を作成します。
- Alpaca MCPサーバーの設定を手動でmcp.jsonファイルに追加します。
{
"alpaca": {
"type": "stdio",
"command": "${workspaceFolder}/venv/bin/python",
"args": ["${workspaceFolder}/alpaca_mcp_server.py"],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key",
}
}
}
注意: Windowsで使用する場合は、"command"パラメータを"${workspaceFolder}\venv\Scripts\python.exe"に置き換えてください。
ユーザー全体の設定の場合:
すべてのワークスペースでMCPサーバーを構成するには、サーバー設定をユーザーのsettings.jsonに追加できます。これにより、複数のプロジェクトで同じサーバー設定を再利用できます。
mcp
VS Codeユーザー設定(settings.json
)でサーバーを指定して、すべてのワークスペースでMCPサーバーを有効にします。
{
"mcp": {
"servers": {
"alpaca": {
"type": "stdio",
"command": "${workspaceFolder}/venv/bin/python",
"args": ["${workspaceFolder}/alpaca_mcp_server.py"],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key",
}
}
}
}
}
Dockerの使用方法
前提条件:
システムにDockerをインストールする必要があります。
最新の公開イメージを実行する(ほとんどのユーザーに推奨)
docker run -it --rm \
-e ALPACA_API_KEY=your_alpaca_api_key \
-e ALPACA_SECRET_KEY=your_alpaca_secret_key \
ghcr.io/chand1012/alpaca-mcp-server:latest
これにより、サーバーの最新の公開バージョンが取得され、実行されます。your_alpaca_api_key
とyour_alpaca_secret_key
を実際のキーに置き換えてください。サーバーがポート(例: 8080)を公開する場合は、コマンドに-p 8080:8080
を追加します。
ローカルでビルドして実行する(開発またはカスタム変更用)
docker build -t alpaca-mcp-server .
docker run -it --rm \
-e ALPACA_API_KEY=your_alpaca_api_key \
-e ALPACA_SECRET_KEY=your_alpaca_secret_key \
alpaca-mcp-server
サーバーの修正版または開発版を実行したい場合は、これを使用してください。
Claude Desktopでの使用
{
"mcpServers": {
"alpaca": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "ALPACA_API_KEY",
"-e", "ALPACA_SECRET_KEY",
"ghcr.io/chand1012/alpaca-mcp-server:latest"
],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key"
}
}
}
}
環境変数は-e
フラグまたは"env"
オブジェクトのいずれかで設定できますが、両方で設定することはできません。Claude Desktopの場合は、"env"
オブジェクトを使用してください。
セキュリティに関する注意:
APIキーを共有したり、公開リポジトリにコミットしたりしないでください。特に共有または本番環境では、シークレットを環境変数として渡す際には注意してください。
高度なDockerの使用方法については:
公式のDockerドキュメントを参照してください。
実際の取引のためのAPIキー設定
このMCPサーバーは、安全なテストのためにデフォルトでAlpacaのペーパー取引APIに接続します。
実際の資金での実際の取引を有効にするには、次の設定ファイルを更新します。
🔐 2箇所でAPI資格情報を設定する:
- プロジェクトディレクトリの
.env
ALPACA_API_KEY = "your_alpaca_api_key_for_live_account"
ALPACA_SECRET_KEY = "your_alpaca_secret_key_for_live_account"
PAPER = False
TRADE_API_URL = None
TRDE_API_WSS = None
DATA_API_URL = None
STREAM_DATA_WSS = None
- Claude for Desktopの設定
claude_desktop_config.json
で、実際のアカウントのキーを環境変数として提供します。
{
"mcpServers": {
"alpaca": {
"command": "<project_root>/venv/bin/python",
"args": [
"/path/to/alpaca_mcp_server.py"
],
"env": {
"ALPACA_API_KEY": "your_alpaca_api_key_for_live_account",
"ALPACA_SECRET_KEY": "your_alpaca_secret_key_for_live_account"
}
}
}
}
利用可能なツール
アカウントとポジション
get_account_info()
– 残高、証拠金、およびアカウントのステータスを表示
get_positions()
– すべての保有資産をリスト表示
get_open_position(symbol)
– 特定のポジションの詳細情報
close_position(symbol, qty|percentage)
– ポジションの一部またはすべてをクローズ
close_all_positions(cancel_orders)
– ポートフォリオ全体を清算
株式市場データ
get_stock_quote(symbol)
– リアルタイムの売り気配/買い気配相場
get_stock_bars(symbol, start_date, end_date)
– OHLCVの過去のバー
get_stock_latest_trade(symbol)
– 最新の市場取引価格
get_stock_latest_bar(symbol)
– 最新のOHLCバー
get_stock_trades(symbol, start_time, end_time)
– 取引レベルの履歴
注文
get_orders(status, limit)
– すべてまたはフィルタリングされた注文を取得
place_stock_order(symbol, side, quantity, order_type="market", limit_price=None, stop_price=None, trail_price=None, trail_percent=None, time_in_force="day", extended_hours=False, client_order_id=None)
– 任意のタイプ(成行、指値、逆指値、逆指値指値、トレイリング逆指値)の株式注文を入力
cancel_order_by_id(order_id)
– 特定の注文をキャンセル
cancel_all_orders()
– すべてのオープン注文をキャンセル
オプション
get_option_contracts(underlying_symbol, expiration_date)
– 契約を取得
get_option_latest_quote(option_symbol)
– 契約の最新の売り気配/買い気配
get_option_snapshot(symbol_or_symbols)
– ギリシャ文字と原資産を取得
place_option_market_order(legs, order_class, quantity)
– オプション戦略を実行
市場情報と企業アクション
get_market_clock()
– 市場の開閉時間スケジュール
get_market_calendar(start, end)
– 休日と取引日
get_corporate_announcements(...)
– 収益、配当、株式分割
ウォッチリスト
create_watchlist(name, symbols)
– 新しいリストを作成
update_watchlist(id, name, symbols)
– 既存のリストを変更
get_watchlists()
– すべての保存されたウォッチリストを取得
資産
get_asset_info(symbol)
– 資産のメタデータを検索
get_all_assets(status)
– すべての取引可能な商品をリスト表示
自然言語クエリの例
取引から企業データ、オプション戦略まで、50の実際の例については、以下の「クエリ例」セクションを参照してください。
基本的な取引
- 現在のアカウント残高と購入力はいくらですか?
- 現在のポジションを表示してください。
- 市場価格でAAPLの株式を10株買います。
- 指値300ドルでTSLAの株式を5株売ります。
- すべてのオープン株式注文をキャンセルします。
- IDがabc123の注文をキャンセルします。
- GOOGLの全ポジションを清算します。
- NVDAのポジションの10%をクローズします。
- 現在、AMZNの株式を何株保有していますか?
- 指値450ドルでMSFTの株式を100株買う注文を入れます。
- 成行でMETAの株式を25株売る注文を入れます。
オプション取引
- 来月満期のAAPLの利用可能なオプション契約を表示してください。
- AAPL250613C00200000の最新の相場を取得してください。
- SPY250627P00400000のオプションスナップショットを取得してください。
- 来週満期のQQQコールの2契約のポジションを清算します。
- 来週の金曜日に満期のAAPLのコールオプションを1つ買う成行注文を入れます。
- TSLA250620P00500000のオプションギリシャ文字は何ですか?
- 現在の市場価格の±5%以内の行使価格を持つすべてのTSLAオプション契約を見つけてください。
- 6月に満期のSPYのすべてのコールオプション契約を取得してください。
- AAPLの6月6日のオプションを使用してブルコールスプレッドを実行します:行使価格190.00のものと行使価格200.00のもの。
市場情報
- 現在、米国株式市場は開いていますか?
- 今日の市場の開閉時間はいつですか?
- 来週の市場カレンダーを表示してください。
- 今月、主要なテクノロジー株の企業発表はありますか?
- SPYの次の配当発表はいつですか?
- 明日の収益発表をリスト表示してください。
過去とリアルタイムのデータ
- 過去5取引日のAAPLの日次価格履歴を表示してください。
- TSLAの昨日の終値はいくらでしたか?
- GOOGの最新のバーを取得してください。
- NVDAの最新の取引価格はいくらでしたか?
- MSFTの最新の相場を表示してください。
- AMDの最後の100件の取引を取得してください。
- 先週の火曜日から金曜日までのAMZNの日内バーを表示してください。
注文
- 今週のすべてのオープンおよび約定済みの注文を表示してください。
- AAPLに関する注文は何がありますか?
- 過去3日間に入力したすべての指値注文をリスト表示してください。
- 注文をステータスでフィルタリングします:約定済み。
- 昨日の注文履歴を取得してください。
ウォッチリスト
- AAPL、MSFT、およびNVDAを含む「テクノロジー株」という名前の新しいウォッチリストを作成します。
- 「テクノロジー株」ウォッチリストを更新して、TSLAとAMZNを含めます。
- 「配当株選択」ウォッチリストにはどの株が含まれていますか?
- 「成長型ポートフォリオ」ウォッチリストからMETAを削除します。
- すべての既存のウォッチリストをリスト表示してください。
資産情報
- 資産'AAPL'の詳細を検索してください。
- すべての取引可能な米国大型株をリスト表示してください。
- 取引量が上位5位の取引可能な暗号資産を表示してください。
- ステータスが'アクティブ'のすべての資産をフィルタリングして表示してください。
- シンボルが'GOOGL'の株式の詳細を表示してください。
複合シナリオ
- 今日の市場の開閉時間を取得し、指値340ドルでTSLAを買う注文を入れる前に購入力を表示してください。
- SPYの7月3日のオプションを使用してブルコールスプレッドを実行します:現在のSPY価格より5%高いものを買い、3%低いものを売ります。
出力例
MCPサーバーは、さまざまな取引クエリに対して詳細で見やすい形式の応答を提供します。以下にいくつかの例を示します。
オプションギリシャ文字分析
クエリ: "What are the option Greeks for TSLA250620P00500000?"
応答:
オプションの詳細:
- 現在の売り気配/買い気配: $142.62 / $143.89
- 最後の取引価格: $138.85
- インプライドボラティリティ: 92.54%
ギリシャ文字:
- デルタ: -0.8968(非常に弱気)
- ガンマ: 0.0021(変化率が低い)
- シータ: -0.2658(時間減衰: $26.58/日)
- ベガ: 0.1654(ボラティリティ感度)
- ロー: -0.3060(金利感度)
重要な洞察:
- 高いインプライドボラティリティ(92.54%)
- 深くインザマネー(デルタ: -0.90)
- 大きな時間減衰($27/日)
マルチレッグオプション注文
クエリ: "Place a bull call spread using AAPL June 6th options: one with a 190.00 strike and the other with a 200.00 strike."
応答:
注文の詳細:
- 注文ID: fc1c04b1-8afa-4b2d-aab1-49613bbed7cb
- 注文クラス: マルチレッグ(MLEG)
- ステータス: 新規待機中
- 数量: 1スプレッド
スプレッドのレッグ:
-
ロングレッグ(買い):
- AAPL250606C00190000(行使価格$190.00)
- ステータス: 新規待機中
-
ショートレッグ(売り):
- AAPL250606C00200000(行使価格$200.00)
- ステータス: 新規待機中
戦略の概要:
- 最大利益: スプレッドあたり$10.00
- 最大損失: 支払った純借入金
- 損益分岐点: $190 + 支払った純借入金
これらの例は、サーバーが以下のことを提供できることを示しています。
- 詳細な市場データ分析
- 包括的な注文実行の詳細
- 明確な戦略の説明
- 見やすい形式の応答
サーバーは、サポートされているすべてのクエリに対してこのレベルの詳細と形式を維持し、提供された情報を理解して行動するのを容易にします。
⚠️ セキュリティに関する注意
このサーバーは実際の取引を行い、ポートフォリオにアクセスできます。APIキーを機密情報として扱ってください。特に複雑なオプション戦略やマルチレッグ取引については、LLMが提案するすべてのアクションを慎重にレビューしてください。
📄 ライセンス
MIT