gold-mcp

gold-mcp

一个 MCP 服务，可将公开黄金（XAUUSD）市场数据接入 Claude、ChatGPT、Cursor、Windsurf、Cline、Zed 以及任何其他 Model Context Protocol 客户端。

免费层（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 — 历史 K 线（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 — 将越南本地报价与全球平价进行比较
• gold_market_snapshot — 单次调用汇总器 + 项目符号摘要
• diagnostic — 显示许可证套餐 + 可用工具
• cache_purge — 清理过期缓存条目

通过 Binance 公共 WebSocket 获取实时 PAXG（v4.1 新增，无需 API 密钥）：

• paxg_worker_status — WebSocket 工作线程健康状态 + tick 计数
• get_paxg_tick — 最新 PAXG tick（与 XAU/USD 的追踪误差在 0.1-0.3% 以内）
• get_paxg_ohlcv_realtime — 根据本地 tick 日志汇总 PAXG K 线

MT5 BYOK 适配器（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 数据
• 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 — 按 Sharpe / PF / 收益进行网格搜索
• gold_intraday_seasonality — 按小时 / 交易时段分组

Ultra —— 机构分析师工具包（18 项专属工具）

聪明钱概念（SMC）

• smc_full_scan —— 综合 SMC 趋势倾向（结构 + OB + FVG + 扫流动性）
• detect_order_blocks —— 使用冲量 ATR 过滤识别看涨／看跌 OB
• detect_fair_value_gaps —— 识别 3 根 K 线的不平衡，并跟踪回补情况
• 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 —— Ralph Vince 的几何均值最大化 f
• risk_of_ruin —— 使用蒙特卡洛计算破产概率

蒙特卡洛 + VaR

• monte_carlo_paths —— 使用自助法或参数法进行路径模拟
• value_at_risk —— 历史 VaR + 条件 VaR
• prob_hit_target_or_stop —— 使用 MC 计算交易概率，并以 R 倍数表示期望值

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 / Agent 模式

设置 → 连接器 → 添加 MCP 服务：

Command: python
Args:    -m gold_mcp.server

3. 试用

用通俗的英语向模型提问。示例：

"黄金现在走势如何？与今天的宏观市场表现（DXY、收益率、VIX）相比如何？"

"展示黄金最近 24 根小时 K 线，以及与白银和 DXY 的 60 天相关性。"

"给我一份黄金市场快照——综合价格、宏观背景、相关性和星期效应。"

"现在 USD/VND 的汇率是多少？以 VND/两表示的隐含世界平价金价是多少？如果 SJC 报价为 1.45 亿，溢价是多少？"

为什么要做这个项目

大模型擅长分析黄金，但无法获取实时市场数据、推动黄金走势的宏观市场信息，也无法按需获取清晰的相关性矩阵。 这个服务是 MCP 客户端与公开 Yahoo Finance 数据之间小巧、免费的桥梁，任何研究人员都能访问这些数据——它将数据封装为类型明确的工具，让模型自动选择合适的工具。

这个项目最初是为了学习 MCP 架构而开展的学习项目，后来逐渐发展成足以发布给社区使用的实用工具。

升级到 Pro / Premium

将 GOLD_MCP_LICENSE_KEY 添加到 MCP 配置的环境变量区块：

"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）。

贡献

本项目有意保持小巧。我们欢迎符合以下模式的贡献：

• 封装单个公开数据源的小型、专注的工具
• 返回包含命名键和简短解读字段的结构化 JSON
• 不涉及私人数据、抓取的凭据或特定经纪商的路径
• 不提供交易建议的工具

详情请参阅 CONTRIBUTING.md，了解如何报告安全问题，请参阅 SECURITY.md。

测试

pip install -e ".[dev]"
pytest

CI 会在每次推送和拉取请求时，在 Linux、macOS 和 Windows 上使用 Python 3.10/3.11/3.12 运行测试套件。

免责声明

gold-mcp 是一款仅用于教育和研究目的的数据与分析工具。任何工具返回的内容均不构成投资建议、推荐或招揽。市场存在风险；您需对自己的决策负责。

许可证

MIT — 请参阅 LICENSE。