Schwab MCP

🚀 スワブMCPサーバー

モデルコンテキストプロトコル（MCP）サーバーで、ClaudeなどのAIアシスタントが、公式のスワブAPIを通じて、スワブ証券の口座や市場データと安全にやり取りできるようになります。

🚀 クイックスタート

このMCPサーバーは、AIアシスタントとスワブAPIの間の橋渡しとして機能し、以下のような機能を提供します。

• 安全なOAuth認証：PKCEを使用したスワブのOAuth 2.0フローを実装し、安全な認証を行います。
• 包括的な取引ツール：口座、注文、相場、取引履歴にアクセスできます。
• 市場データツール：リアルタイム相場、価格履歴、市場時間、市場の大きな変動銘柄、オプションチェーンを提供します。
• 口座のプライバシー：機密情報を保護するため、口座識別子を自動的に隠す機能が組み込まれています。
• エンタープライズ対応：Cloudflare WorkersとDurable Objectsを使用してデプロイされ、状態管理が可能です。

✨ 主な機能

取引ツール

• 口座管理
  • getAccounts：ポジションと残高を含むすべての口座情報を取得します。
  • getAccountNumbers：口座識別子のリストを取得します。
• 注文管理
  • getOrder：注文IDで注文を取得します。
  • getOrders：ステータス、時間範囲、銘柄でフィルタリングして注文を取得します。
  • getOrdersByAccountNumber：口座番号で注文を取得します。
  • cancelOrder：注文をキャンセルします（実験的）。
  • placeOrder：注文を発注します（実験的）。
  • replaceOrder：注文を置き換えます（実験的）。
• 市場相場
  • getQuotes：複数の銘柄のリアルタイム相場を取得します。
  • getQuoteBySymbolId：単一の銘柄の詳細な相場を取得します。
• 取引履歴
  • getTransactions：日付でフィルタリングして、すべての口座の取引履歴を取得します。
• ユーザー設定
  • getUserPreference：ユーザーの取引設定を取得します。

市場データツール

• 銘柄検索
  • searchInstruments：銘柄で証券を検索し、基本データや参照データを取得します。
• 価格履歴
  • getPriceHistory：期間と頻度をカスタマイズして、過去の価格データを取得します。
• 市場時間
  • getMarketHours：日付ごとに市場の営業時間を確認します。
  • getMarketHoursByMarketId：特定の市場の情報を取得します。
• 市場の大きな変動銘柄
  • getMovers：指数（$SPX、$COMPX、$DJI）で市場の大きな変動銘柄を検索します。
• オプションチェーン
  • getOptionChain：ギリシャ文字を含む完全なオプションチェーンデータを取得します。
  • getOptionExpirationChain：オプションの満期日を取得します。

📦 インストール

前提条件

1. スワブ開発者アカウント：スワブ開発者ポータルで登録してください。
2. Cloudflareアカウント：デプロイに必要です（Durable Objectsを使用するにはWorkersの有料プランが必要です）。
3. Node.js：バージョン22.x以上。
4. Wrangler CLI：npmを通じてインストールしてください（開発依存関係に含まれています）。

クイックセットアップ

git clone <repository-url>
cd schwab-mcp
npm install

# Cloudflareで認証（初回のみ）
npx wrangler login

# OAuthトークンを保存するためのKV名前空間を作成
npx wrangler kv:namespace create "OAUTH_KV"
# 出力からIDをメモしておく - 設定に必要です

# 個人用の設定をセットアップ
cp wrangler.example.jsonc wrangler.jsonc
# wrangler.jsoncを編集して：
# 1. YOUR_KV_NAMESPACE_ID_HEREを上記のIDに置き換える
# 2. 名前を一意のものに変更する（例："schwab-mcp-yourname"）

# シークレットを設定
npx wrangler secret put SCHWAB_CLIENT_ID      # あなたのスワブアプリキー
npx wrangler secret put SCHWAB_CLIENT_SECRET  # あなたのスワブアプリシークレット
npx wrangler secret put SCHWAB_REDIRECT_URI   # https://your-worker-name.workers.dev/callback
npx wrangler secret put COOKIE_ENCRYPTION_KEY # 生成方法：openssl rand -hex 32

# デプロイ
npm run deploy

設定に関する注意事項

• wrangler.example.jsonc - テンプレート設定（コミットされています）
• wrangler.jsonc - あなたの個人用設定（gitで無視され、テンプレートから作成されます）
• .dev.vars - ローカル開発用のシークレット（gitで無視され、オプション）

wrangler.jsoncはgitで無視されるため、シークレットを公開することなく、個人用の設定で安全に開発とテストを行うことができます。

詳細な設定

1. スワブアプリを作成する

1. スワブ開発者ポータルにログインします。
2. 新しいアプリを作成します。
   • アプリ名：あなたのMCPサーバーの名前
   • コールバックURL：https://schwab-mcp.<your-subdomain>.workers.dev/callback
   • アプリタイプ：使用ケースに応じて、個人用またはサードパーティ
3. アプリキー（クライアントID）をメモし、アプリシークレットを生成します。

2. 環境変数を設定する

クイックセットアップと同じシークレットを設定する必要があります（上記を参照）。

GitHub Actionsによるデプロイ

自動デプロイを行うには、以下のGitHubリポジトリシークレットを追加します。

1. CLOUDFLARE_API_TOKEN：あなたのCloudflare APIトークン
2. OAUTH_KV_ID：あなたのKV名前空間ID

ワークフローは、mainブランチにプッシュすると、検証とデプロイを処理します。Cloudflareのシークレットは、依然としてwrangler secretを通じて設定する必要があります。

インスペクターを使用したテスト

MCPインスペクターを使用してデプロイをテストします。

npx @modelcontextprotocol/inspector@latest

https://schwab-mcp.<your-subdomain>.workers.dev/sseを入力して接続します。スワブでの認証を求められます。

💻 使用例

Claudeデスクトップの設定

1. Claudeの統合を使用する

1. Claudeデスクトップの設定にアクセスします。
2. "統合"タブをクリックします。
3. "カスタム統合を追加"ボタンをクリックします。
4. 統合名に"Schwab"を入力します。
5. MCPサーバーのURLを入力します：https://schwab-mcp.<your-subdomain>.workers.dev/sse
6. "追加"ボタンをクリックします。
7. "接続"をクリックすると、スワブの認証フローが開始されます。

2. Claudeデスクトップの設定にMCPサーバーを追加する

Claudeデスクトップの設定ファイルに以下を追加します。

{
    "mcpServers": {
        "schwab": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://schwab-mcp.<your-subdomain>.workers.dev/sse"
            ]
        }
    }
}

Claudeデスクトップを再起動します。初めてスワブのツールを使用するとき、認証用のブラウザウィンドウが開きます。

コマンドの例

接続後、Claudeに以下のようなことを依頼できます。

• "私のスワブ口座の残高を表示して"
• "AAPLの相場を取得して"
• "今日の$SPXで大きく動いた銘柄は何ですか？"
• "TSLAのオプションチェーンを表示して"
• "先週の最近の取引履歴を取得して"

ローカル開発

ローカル開発のために、.dev.varsファイルを作成します（gitによって自動的に無視されます）。

SCHWAB_CLIENT_ID=your_development_app_key
SCHWAB_CLIENT_SECRET=your_development_app_secret
SCHWAB_REDIRECT_URI=http://localhost:8788/callback
COOKIE_ENCRYPTION_KEY=your_random_key_here
LOG_LEVEL=DEBUG  # オプション：デバッグログを有効にする

ローカルで実行します。

npm run dev
# サーバーはhttp://localhost:8788で利用可能になります

MCPインスペクターを使用してhttp://localhost:8788/sseに接続してテストします。

🔧 技術詳細

技術スタック

• ランタイム：Cloudflare WorkersとDurable Objects
• 認証：@cloudflare/workers-oauth-providerを通じたPKCE付きOAuth 2.0
• APIクライアント：型安全なスワブAPIアクセスのための@sudowealth/schwab-api
• MCPフレームワーク：workers-mcpアダプターを備えた@modelcontextprotocol/sdk
• 状態管理：トークンのためのKVストレージ、セッション状態のためのDurable Objects

セキュリティ機能

1. PKCE付きOAuth 2.0：承認コードの傍受を防ぐ安全な認証フロー
2. 強化されたトークン管理
   • 自動移行機能を備えた集中型KVトークンストア
   • 有効期限の5分前に自動的にトークンを更新
   • TTLを持つ31日間のトークン持続性
3. 口座情報の隠蔽：機密性の高い口座識別子が自動的に表示名に置き換えられます。
4. 状態のセキュリティ：状態パラメータの整合性を保つためのHMAC - SHA256署名
5. クッキーの暗号化：クライアントの承認状態がAES - 256で暗号化されます。
6. シークレットの隠蔽：ログ内の機密データが自動的にマスクされます。

📚 ドキュメント

開発に利用可能なスクリプト

npm run dev          # ポート8788で開発サーバーを起動します
npm run deploy       # Cloudflare Workersにデプロイします
npm run typecheck    # TypeScriptの型チェックを実行します
npm run lint         # ESLintを自動修正付きで実行します
npm run format       # Prettierでコードをフォーマットします
npm run validate     # 型チェックとリントを一緒に実行します

デバッグ

サーバーには、構成可能なレベルの包括的なロギングが含まれています。

• 開発環境：色付きのログを持つターミナル出力
• 本番環境：Cloudflareダッシュボード → Workers → ログ
• ログレベル：DEBUG、INFO、WARN、ERROR（LOG_LEVEL環境変数で設定）

詳細なOAuthフローとAPIのやり取りを見るために、デバッグログを有効にします。

# ローカル開発の場合
echo "LOG_LEVEL=DEBUG" >> .dev.vars

# 本番環境の場合
npx wrangler secret put LOG_LEVEL --secret="DEBUG"

エラーハンドリング

サーバーは、特定のエラータイプを持つ堅牢なエラーハンドリングを実装しています。

• 認証エラー（401）：再認証を促します。
• クライアントエラー（400）：無効なパラメータ、欠落したデータ。
• サーバーエラー（500）：APIの失敗、設定の問題。
• ネットワークエラー（503）：バックオフ付きで自動的に再試行します。 すべてのエラーには、スワブAPIのトラブルシューティング用のリクエストIDが含まれています。

🤝 コントリビューション

1. リポジトリをフォークします。
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）。
3. 変更をコミットします（git commit -m 'Add amazing feature'）。
4. ブランチにプッシュします（git push origin feature/amazing-feature）。
5. プルリクエストを作成します。

📄 ライセンス

MIT

🛠️ トラブルシューティング

一般的な問題

1. "KV名前空間が見つかりません"エラー
   • KV名前空間を作成し、wrangler.jsoncを更新したことを確認してください。
   • npx wrangler kv:namespace listを実行して確認します。
2. 認証失敗
   • スワブアプリの設定でリダイレクトURIが正確に一致することを確認してください。
   • npx wrangler secret listですべてのシークレットが正しく設定されていることを確認します。
   • 詳細なOAuthフローを見るために、デバッグログを有効にします。
3. "Durable Objectsが利用できません"エラー
   • Cloudflare Workersの有料プランを持っていることを確認してください。
   • Durable Objectsは無料プランでは利用できません。
4. トークン更新の問題
   • サーバーは有効期限の5分前に自動的にトークンを更新します。
   • トークンは自動的にclientIdからschwabUserIdキーに移行されます。
   • 保存されたトークンをKV名前空間で確認します：npx wrangler kv:key list --namespace-id=<your-id>

🆕 最近の更新

• 強化されたトークン管理：集中型KVトークンストアにより、トークンの不一致を防ぎます。
• セキュリティの向上：HMAC - SHA256による状態検証と自動シークレット隠蔽。
• 改善されたエラーハンドリング：スワブAPIのエラーマッピングを持つ構造化されたエラータイプ。
• 設定可能なロギング：OAuthとAPIの問題のトラブルシューティング用のデバッグモード。

🙏 謝辞

• Cloudflare Workersを使用して構築されています。
• Model Context Protocolを使用しています。
• @sudowealth/schwab-apiによって提供されています。