gold-mcp

gold-mcp

公開金（XAUUSD）市場データを Claude、ChatGPT、Cursor、Windsurf、Cline、Zed、およびその他すべての Model Context Protocol クライアントで利用できるようにする MCP サーバーです。

無料プラン（13 個のツール＋オプションの 8 ツール MT5 BYOK アダプター）はすべての機能を利用でき、永久に無料です。Pro、Premium、Ultra プランでは、オフラインの Ed25519 ライセンスキーを使って、高度な TA、バックテスト、SMC スイート、リスク管理、AI アナリストを利用できます。SaaS も、サーバーへの定期通信もありません。

教育および研究目的のみ — 金融アドバイスではありません。

プラン

プラン	ツール	ライセンス	価格の目安
Free	13（＋オプションの 8 MT5 BYOK）	なし	$0
Pro	＋7（合計 20）	GOLD_MCP_LICENSE_KEY env	$9-19/mo
Premium	＋4（合計 24）	GOLD_MCP_LICENSE_KEY env	$29-49/mo
Ultra	＋18（合計 42、MT5 BYOK 併用時は 50）	GOLD_MCP_LICENSE_KEY env	$99-149/mo

Free — 公開金データ＋リアルタイム PAXG＋MT5 BYOK（13＋8 ツール）

公開金データ（Yahoo Finance）：

• get_gold_price — 最新の金の終値＋24 時間の変動
• get_gold_ohlcv — 過去のバー（1m → 1mo）
• get_macro_context — DXY、US10Y/02Y、SPX、VIX、BTC、銀、原油
• get_gold_correlations — 金とマクロ指標の相関行列
• get_gold_seasonality — 曜日別／月別のリターン統計
• get_vn_macro — USD/VND＋VND 建ての世界パリティ金価格の推定値
• estimate_vn_gold_premium — VN の現地価格と世界パリティ価格を比較
• gold_market_snapshot — 1 回の呼び出しでデータを集約＋箇条書きの概要を表示
• diagnostic — ライセンスのプラン＋利用可能なツールを表示
• cache_purge — 期限切れのキャッシュエントリーを一括削除

Binance の公開 WebSocket 経由のリアルタイム PAXG（NEW v4.1、API キー不要）：

• paxg_worker_status — WS ワーカーの状態＋ティック数
• get_paxg_tick — 最新の PAXG ティック（XAU/USD を 0.1〜0.3% 以内で追跡）
• get_paxg_ohlcv_realtime — ローカルのティックログから集計した PAXG バー

MT5 BYOK アダプター（NEW v4.1、オプション。pip install 'gold-mcp[mt5]' でインストール、Windows）：

• mt5_attach / mt5_detach / mt5_status — 接続済みのターミナルを管理
• mt5_find_symbol — ブローカー固有の XAUUSD シンボルを解決
• mt5_get_tick / mt5_get_ohlcv / mt5_get_ticks — ご自身のターミナルから読み取り
• mt5_account_info — 残高／有効証拠金／レバレッジ
• 認証情報がサーバーの外に送信されることはありません。MT5 ターミナルはご自身で実行します。

Pro — 高度な TA＋複数時間足＋アラート

• analyze_gold_advanced — ボリンジャー＋一目均衡表＋フィボナッチ
• multi_timeframe_snapshot — 5m／1h／4h／1d を 1 回の呼び出しで取得
• gold_correlation_regime — DXY のデカップリングなどを検出
• get_gold_setups — 複数の指標のコンフルエンスをスキャン
• create_gold_alert / list_gold_alerts / delete_gold_alert

Premium — バックテスト＋リサーチ

• backtest_gold_strategy — 4 つの戦略をベクトル化して実行
• gold_walk_forward — ローリング方式のアウトオブサンプル検証
• optimize_gold_strategy — シャープレシオ／PF／リターンを基準にグリッドサーチ
• gold_intraday_seasonality — 時間別／セッション別に分類

Ultra — 機関投資家向け分析ツールキット（専用ツール18種）

スマートマネーコンセプト（SMC）

• smc_full_scan — SMCの複合バイアス（構造＋OB＋FVG＋スイープ）
• detect_order_blocks — インパルスATRフィルタリングによる強気／弱気のOB検出
• detect_fair_value_gaps — 3本のローソク足の不均衡＋埋め戻しの追跡
• detect_liquidity_sweeps — ストップ狩りの検出（ブレイク＋反転）
• detect_market_structure — スイングフラクタルにおけるCHOCH／BOSのラベリング

レジーム＋マルチタイムフレーム

• classify_regime — ハースト指数＋Lo-MacKinlay分散比の複合判定
• mtf_alignment — D1／H4／H1のコンフルエンスと整合性スコア（0～100）

ポジションサイジング＋リスク

• kelly_fraction — 安全性を考慮し、デフォルトでハーフケリーを使用
• fixed_fractional_size — 従来型のR％サイジング
• optimal_f — ラルフ・ヴィンスによる幾何平均を最大化するf
• risk_of_ruin — モンテカルロ法による破産確率

モンテカルロ＋VaR

• monte_carlo_paths — ブートストラップまたはパラメトリックなパスシミュレーション
• value_at_risk — ヒストリカルVaR＋条件付きVaR
• prob_hit_target_or_stop — R倍数での期待値を含む、MC取引確率

AIアナリスト（BYOK Anthropic）

• ai_daily_briefing — Claude Sonnet 4.6による構造化JSON分析
• ai_setup_explanation — より安価なHaiku 4.5による平易な説明

レポート生成

• generate_html_tearsheet — 洗練されたスタンドアロンHTMLレポート
• generate_markdown_briefing — 持ち運び可能なMarkdown形式の日次サマリー

クイックスタート

1. インストール

git clone https://github.com/ThaiTrevor/gold-mcp.git
cd gold-mcp
pip install -e .

Python 3.10以降が必要です。ほかにセットアップや環境変数、データファイルは不要です。

2. MCPクライアントに接続する

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json（Windows）または ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）を編集します。

{
  "mcpServers": {
    "gold-mcp": {
      "command": "python",
      "args": ["-m", "gold_mcp.server"]
    }
  }
}

Claude Desktopを再起動します。ツールはプラグアイコンの下に表示されます。

Claude Code（CLI）

claude mcp add --scope user gold-mcp -- python -m gold_mcp.server

Cursor／Windsurf／Cline／Continue／Zed

~/.cursor/mcp.json（またはクライアントに対応するファイル）：

{
  "mcpServers": {
    "gold-mcp": {
      "command": "python",
      "args": ["-m", "gold_mcp.server"]
    }
  }
}

ChatGPT Desktop／エージェントモード

設定 → コネクター → MCP サーバーを追加：

Command: python
Args:    -m gold_mcp.server

3. 試してみる

モデルに自然な英語で質問します。例：

「現在の金の動きと、今日のマクロ市場（DXY、利回り、VIX）との比較を教えてください。」

「金の直近24時間分の1時間足と、銀およびDXYとの60日間の相関を見せてください。」

「金のマーケットスナップショットを作成してください。価格、マクロ環境、相関、曜日別の季節性を組み合わせてください。」

「現在のUSD/VNDと、タエル当たりのVND建て理論上の世界平価金価格を教えてください。SJCの提示価格が1億4500万なら、プレミアムはいくらですか？」

このプロジェクトの目的

LLMは金について適切に推論できますが、リアルタイムの市場データや、金を動かすマクロ市場の動向、必要なときにすぐ使えるクリーンな相関行列は参照できません。このサーバーは、MCPクライアントと、すべての研究者がすでにアクセスできる公開Yahoo Financeデータをつなぐ、小さく無料のブリッジです。型付けされたツールとして公開されているため、モデルが適切なツールを自動的に選択します。

MCPアーキテクチャを学ぶための学習プロジェクトとして始まり、コミュニティに公開する価値があるほど役立つものになりました。

Pro／Premiumへのアップグレード

MCP設定の環境変数ブロックにGOLD_MCP_LICENSE_KEYを追加します。

"env": {
  "GOLD_MCP_LICENSE_KEY": "eyJ0aWVy...Ijoi.MEUCI..."
}

MCPクライアントを再起動します。diagnosticを呼び出し、tier_activeが proまたはpremiumを返すことを確認します。新しいツールがすぐに利用可能になります。

完全なテンプレートについては、examples/claude_desktop_config_pro.jsonを参照してください。

アーキテクチャ

gold_mcp/
  server.py            FastMCP wiring with 3-tier gating (21 tools max)
  gold_data.py         yfinance price + OHLCV
  macro_data.py        DXY/yields/SPX/VIX/BTC + correlations
  analytics.py         seasonality
  analyst.py           one-call aggregator (gold_market_snapshot)
  cache.py             TTL filesystem cache (60s → 24h)
  license.py           Ed25519 offline license verification
  issue_license.py     CLI: init-keys, issue, verify
  pro_tools.py         Pro tier: advanced TA, alerts, multi-timeframe
  premium_tools.py     Premium tier: backtest, walk-forward, optimizer
  adapters/
    vn_macro.py        USD/VND + world-parity gold

ライセンスを販売するベンダー向けには、CLIを参照してください。

python -m gold_mcp.issue_license init-keys
# Paste printed PUBLIC_KEY_B64 into gold_mcp/license.py

python -m gold_mcp.issue_license issue --tier pro --email [email protected] --days 30

または、Lemon SqueezyのWebhookハンドラーを実行します（ポートは mcp-byok-templateから取得し、 環境変数名をMCP_BYOK_LICENSE_KEYからGOLD_MCP_LICENSE_KEYに変更してください）。

貢献

このプロジェクトは意図的に小規模にしています。同じパターンに沿った貢献を歓迎します。

• 1 つの公開データソースをラップする、小規模で目的を絞ったツール
• 名前付きキーと短い解釈フィールドを含む、構造化 JSON を返す
• 個人データ、スクレイピングした認証情報、特定のブローカー向けの手順は含めない
• 取引の推奨を行うツールは含めない

詳細は CONTRIBUTING.md を、セキュリティ問題の報告方法は SECURITY.md をご覧ください。

テスト

pip install -e ".[dev]"
pytest

CI では、プッシュとプルリクエストのたびに、Python 3.10/3.11/3.12 を対象として、Linux、macOS、Windows でテストスイートを実行します。

免責事項

gold-mcp は、教育および研究のみを目的としたデータ・分析ツールです。 いずれかのツールが返す情報も、投資アドバイス、推奨、勧誘を構成するものではありません。市場にはリスクが伴います。ご自身の判断については、ご自身で責任を負ってください。

ライセンス

MIT — LICENSE をご覧ください。