Schwab MCP Server

Schwab MCP サーバー

AI アシスタントが公式の Schwab API を通じて Charles Schwab の口座や市場データと 安全に連携できるようにする Model Context Protocol（MCP）サーバーです。

できること

Claude に次のように依頼できます。

• 「Schwab の口座残高と保有ポジションを表示して」
• 「AAPL、GOOGL、MSFT のリアルタイムの気配値を取得して」
• 「$SPX で今日の値上がり・値下がり銘柄は？」
• 「TSLA のグリークス付きオプションチェーンを表示して」
• 「過去 30 日間の取引履歴を取得して」
• 「テクノロジー関連の ETF を検索して」
• 「市場が開いているか確認して」

非公式 MCP サーバー

これは Charles Schwab 向けにコミュニティが開発した非公式の TypeScript MCP サーバーです。Charles Schwab による承認、推奨、認定は受けていません。現状のまま提供されており、機能が不完全または不安定な場合があります。特に金融データや取引を扱う際は、自己責任でご利用ください。

概要

この MCP サーバーは AI アシスタントと Schwab API の間の橋渡しとなり、次の機能を提供します。

• 安全な OAuth 認証：安全な認証のため、PKCE を使用した Schwab の OAuth 2.0 フローを実装
• 包括的な取引ツール：口座、注文、気配値、取引履歴にアクセス
• 市場データツール：リアルタイムの気配値、価格履歴、市場営業時間、値上がり・値下がり銘柄、オプションチェーン
• 口座のプライバシー保護：機密情報を保護するため、口座識別子を自動的にマスキング
• エンタープライズ対応：状態管理に Durable Objects を使用し、Cloudflare Workers にデプロイ

機能

取引ツール

• 口座管理
  • getAccounts：保有ポジションと残高を含む、すべての口座情報を取得
  • getAccountNumbers：口座識別子の一覧を取得
• 注文管理
  • getOrder：ID で注文を取得
  • getOrders：ステータス、期間、シンボルで絞り込んで注文を取得
  • getOrdersByAccountNumber：口座番号で注文を取得
  • cancelOrder：注文をキャンセル（実験的機能）
  • placeOrder：注文を発注（実験的機能）
  • replaceOrder：注文を置き換え（実験的機能）
• 市場の気配値
  • getQuotes：複数のシンボルのリアルタイムの気配値を取得
  • getQuoteBySymbolId：単一のシンボルの詳細な気配値を取得
• 取引履歴
  • getTransactions：日付で絞り込み、すべての口座の取引履歴を取得
• ユーザー設定
  • getUserPreference：ユーザーの取引設定と環境設定を取得

市場データツール

• 金融商品検索
  • searchInstruments：ファンダメンタルデータ／参照データを含め、シンボルで証券を検索
• 価格履歴
  • getPriceHistory：期間と頻度をカスタマイズして過去の価格データを取得
• 市場営業時間
  • getMarketHours：日付を指定して市場の営業時間を確認
  • getMarketHoursByMarketId：特定の市場情報を取得
• 値上がり・値下がり銘柄
  • getMovers：指数（$SPX、$COMPX、$DJI）ごとに市場の値上がり・値下がり上位銘柄を検索
• オプションチェーン
  • getOptionChain：グリークスを含む、オプションチェーンの全データを取得
  • getOptionExpirationChain：オプションの満期日を取得

前提条件

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

はじめに

クイックセットアップ

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

# Authenticate with Cloudflare (first time only)
npx wrangler login

# Create KV namespace for OAuth token storage
npx wrangler kv:namespace create "OAUTH_KV"
# Note the ID from the output - you'll need it for configuration

# Set up your personal configuration
cp wrangler.example.jsonc wrangler.jsonc
# Edit wrangler.jsonc to:
# 1. Replace YOUR_KV_NAMESPACE_ID_HERE with the ID from above
# 2. Change the name to something unique (e.g., "schwab-mcp-yourname")

# Set your secrets
npx wrangler secret put SCHWAB_CLIENT_ID      # Your Schwab App Key
npx wrangler secret put SCHWAB_CLIENT_SECRET  # Your Schwab App Secret
npx wrangler secret put SCHWAB_REDIRECT_URI   # https://your-worker-name.workers.dev/callback
npx wrangler secret put COOKIE_ENCRYPTION_KEY # Generate with: openssl rand -hex 32

# Deploy
npm run deploy

設定に関する注意

• wrangler.example.jsonc - 設定テンプレート（コミット対象）
• wrangler.jsonc - 個人用設定（Git の追跡対象外。テンプレートから作成）
• .dev.vars - ローカル開発用のシークレット（Git の追跡対象外。任意）

wrangler.jsonc は Git の追跡対象外なので、シークレットを公開することなく、個人用の設定で安全に開発やテストを行えます。

詳細な設定

1. Schwab アプリを作成する

1. Schwab Developer Portal にログインします
2. 新しいアプリを作成します：
   • App Name：MCP サーバーの名前
   • Callback URL： https://schwab-mcp.<your-subdomain>.workers.dev/callback
   • App Type：用途に応じて、Personal または third-party
3. App Key（Client ID）を控え、App Secretを生成します

2. 環境変数を設定する

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

GitHub Actions によるデプロイ

デプロイを自動化するには、次の GitHub リポジトリシークレットを追加します：

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

main へのプッシュ時に、ワークフローが検証とデプロイを行います。 Cloudflare のシークレットは、引き続き wrangler secret で設定する必要があります。

Inspector でのテスト

MCP Inspector を使ってデプロイをテストします：

npx @modelcontextprotocol/inspector@latest

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

使い方

Claude Desktop の設定

1. Claude のインテグレーションを使用する

1. Claude Desktop の設定を開きます
2. 「Integrations」タブをクリックします
3. 「Add Custom Integration」ボタンをクリックします
4. インテグレーション名「Schwab」を入力します
5. MCP サーバーの URL を入力します： https://schwab-mcp.<your-subdomain>.workers.dev/sse
6. 「Add」ボタンをクリックします
7. 「Connect」をクリックすると、Schwab の認証フローが開始されます。

2. MCP サーバーを Claude Desktop の設定に追加する

次の内容を Claude Desktop の設定ファイルに追加します：

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

Claude Desktop を再起動します。Schwab のツールを初めて使用すると、認証用のブラウザーウィンドウが開きます。

コマンドの例

接続後、Claude に次のように依頼できます：

• 「Schwab の口座残高を表示して」
• 「AAPL の見積もりを取得して」
• 「今日の $SPX の値上がり銘柄を教えて」
• 「TSLA のオプションチェーンを表示して」
• 「過去 1 週間の最近の取引を取得して」

ローカル開発

ローカル開発では、.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  # Optional: Enable debug logging

ローカルで実行します：

npm run dev
# Server will be available at http://localhost:8788

テストするには、MCP Inspector を使って http://localhost:8788/sse に接続します。

アーキテクチャ

技術スタック

• ランタイム：Durable Objects を使用する Cloudflare Workers
• 認証：@cloudflare/workers-oauth-provider を介した PKCE 対応 OAuth 2.0
• API クライアント：型安全な Schwab 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. Cookie の暗号化：クライアント承認状態を AES-256 で暗号化
6. シークレットのマスキング：ログ内の機密データを自動的にマスキング

開発

利用可能なスクリプト

npm run dev          # Start development server on port 8788
npm run deploy       # Deploy to Cloudflare Workers
npm run typecheck    # Run TypeScript type checking
npm run lint         # Run ESLint with automatic fixes
npm run format       # Format code with Prettier
npm run validate     # Run typecheck and lint together

デバッグ

サーバーには、レベルを設定できる包括的なログ機能が含まれています：

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

詳細な OAuth フローと API のやり取りを確認するには、デバッグログを有効にします：

# For local development
echo "LOG_LEVEL=DEBUG" >> .dev.vars

# For production
npx wrangler secret put LOG_LEVEL --secret="DEBUG"

エラー処理

サーバーは、エラーの種類に応じた堅牢なエラー処理を実装しています。

• 認証エラー（401）：再認証を求めます
• クライアントエラー（400）：無効なパラメーター、データの不足
• サーバーエラー（500）：API の失敗、設定の問題
• ネットワークエラー（503）：バックオフを伴う自動再試行
• すべてのエラーには、Schwab 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 namespace not found」エラー

   • KV namespace を作成し、wrangler.jsonc を更新したことを確認します
   • npx wrangler kv:namespace list を実行して確認します

2. 認証の失敗

   • Schwab アプリの設定で、リダイレクト URI が完全に一致していることを確認します
   • npx wrangler secret list ですべてのシークレットが正しく設定されていることを確認します
   • デバッグログを有効にして、OAuth フローの詳細を確認します

3. 「Durable Objects not available」エラー

   • Cloudflare Workers の有料プランを利用していることを確認します
   • Durable Objects は無料プランでは利用できません

4. トークンの更新に関する問題

   • サーバーは有効期限の5分前にトークンを自動更新します
   • トークンは clientId キーから schwabUserId キーに自動的に移行されます
   • 保存されたトークンを確認するには、KV namespace を確認します： npx wrangler kv:key list --namespace-id=<your-id>

最近の更新

• トークン管理の強化：KV トークンストアを一元化し、トークンの不一致を防止
• セキュリティの向上：HMAC-SHA256 による state 検証とシークレットの自動マスキング
• エラー処理の改善：Schwab API のエラーマッピングに対応した構造化エラータイプ
• ログの設定：OAuth と API の問題をトラブルシューティングするためのデバッグモード

謝辞

• Cloudflare Workers を使用して構築
• Model Context Protocol を使用
• 以下によって実現： @sudowealth/schwab-api