{
  "markdown": "# gold-mcp\n\n<!-- mcp-name: io.github.ThaiTrevor/gold-mcp -->\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![Version](https://img.shields.io/badge/version-4.1.2-green.svg)](https://github.com/ThaiTrevor/gold-mcp/releases)\n[![MCP](https://img.shields.io/badge/MCP-compatible-orange.svg)](https://modelcontextprotocol.io)\n[![CI](https://github.com/ThaiTrevor/gold-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/ThaiTrevor/gold-mcp/actions/workflows/test.yml)\n[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/ThaiTrevor/gold-mcp/blob/main/CONTRIBUTING.md)\n\n**An MCP server that brings public gold (XAUUSD) market data into\nClaude, ChatGPT, Cursor, Windsurf, Cline, Zed, and any other Model\nContext Protocol client.**\n\nFree tier (13 tools + optional 8-tool MT5 BYOK adapter) is fully\nfunctional and stays free forever. Pro, Premium, and Ultra tiers add\nadvanced TA, backtest, SMC suite, risk management, and AI analyst via\nan offline Ed25519 license key — no SaaS, no phone-home.\n\n> **Educational and research use only — not financial advice.**\n\n## Tiers\n\n| Tier | Tools | License | Suggested price |\n|---|---|---|---|\n| **Free** | 13 (+8 optional MT5 BYOK) | None | $0 |\n| **Pro** | +7 (20 total) | `GOLD_MCP_LICENSE_KEY` env | $9-19/mo |\n| **Premium** | +4 (24 total) | `GOLD_MCP_LICENSE_KEY` env | $29-49/mo |\n| **Ultra** | +18 (42 total, 50 with MT5 BYOK) | `GOLD_MCP_LICENSE_KEY` env | $99-149/mo |\n\n### Free — public gold data + realtime PAXG + MT5 BYOK (13 + 8 tools)\n\n**Public gold data (Yahoo Finance):**\n- `get_gold_price` — latest gold close + 24h change\n- `get_gold_ohlcv` — historical bars (1m → 1mo)\n- `get_macro_context` — DXY, US10Y/02Y, SPX, VIX, BTC, silver, oil\n- `get_gold_correlations` — gold-vs-macro correlation matrix\n- `get_gold_seasonality` — day-of-week / monthly return stats\n- `get_vn_macro` — USD/VND + implied world-parity gold price in VND\n- `estimate_vn_gold_premium` — compare local VN quote to world parity\n- `gold_market_snapshot` — one-call aggregator + bulleted summary\n- `diagnostic` — show license tier + available tools\n- `cache_purge` — sweep expired cache entries\n\n**Realtime PAXG via Binance public WebSocket (NEW v4.1, no API key):**\n- `paxg_worker_status` — WS worker health + tick count\n- `get_paxg_tick` — last PAXG tick (tracks XAU/USD within 0.1-0.3%)\n- `get_paxg_ohlcv_realtime` — aggregated PAXG bars from local tick log\n\n**MT5 BYOK adapter (NEW v4.1, optional via `pip install 'gold-mcp[mt5]'`, Windows):**\n- `mt5_attach` / `mt5_detach` / `mt5_status` — manage attached terminal\n- `mt5_find_symbol` — broker-specific XAUUSD symbol resolution\n- `mt5_get_tick` / `mt5_get_ohlcv` / `mt5_get_ticks` — read from your terminal\n- `mt5_account_info` — balance / equity / leverage\n- *No credentials cross the server. You run your own MT5 terminal.*\n\n### Pro — advanced TA + multi-timeframe + alerts\n- `analyze_gold_advanced` — Bollinger + Ichimoku + Fibonacci\n- `multi_timeframe_snapshot` — 5m / 1h / 4h / 1d in one call\n- `gold_correlation_regime` — detects DXY decoupling, etc.\n- `get_gold_setups` — multi-indicator confluence scanner\n- `create_gold_alert` / `list_gold_alerts` / `delete_gold_alert`\n\n### Premium — backtest + research\n- `backtest_gold_strategy` — 4 strategies, vectorized\n- `gold_walk_forward` — rolling out-of-sample validation\n- `optimize_gold_strategy` — grid search by Sharpe / PF / return\n- `gold_intraday_seasonality` — hourly / session bucketing\n\n### Ultra — institutional analyst toolkit (18 exclusive tools)\n\n**Smart Money Concepts (SMC)**\n- `smc_full_scan` — composite SMC bias (structure + OB + FVG + sweeps)\n- `detect_order_blocks` — bullish/bearish OB with impulse ATR filtering\n- `detect_fair_value_gaps` — 3-candle imbalances + fill tracking\n- `detect_liquidity_sweeps` — stop-hunt detection (breach + reverse)\n- `detect_market_structure` — CHOCH/BOS labeling on swing fractals\n\n**Regime + Multi-Timeframe**\n- `classify_regime` — composite Hurst exponent + Lo-MacKinlay variance ratio\n- `mtf_alignment` — D1/H4/H1 confluence with alignment score 0-100\n\n**Position sizing + risk**\n- `kelly_fraction` — half-Kelly default for safety\n- `fixed_fractional_size` — classic R% sizing\n- `optimal_f` — Ralph Vince geometric-mean-maximizing f\n- `risk_of_ruin` — Monte Carlo ruin probability\n\n**Monte Carlo + VaR**\n- `monte_carlo_paths` — bootstrap or parametric path simulation\n- `value_at_risk` — historical VaR + Conditional VaR\n- `prob_hit_target_or_stop` — MC trade probability with EV in R-multiples\n\n**AI Analyst (BYOK Anthropic)**\n- `ai_daily_briefing` — structured JSON read from Claude Sonnet 4.6\n- `ai_setup_explanation` — cheaper Haiku 4.5 plain-English read\n\n**Report generation**\n- `generate_html_tearsheet` — polished standalone HTML report\n- `generate_markdown_briefing` — portable Markdown daily summary\n\n## Quickstart\n\n### 1. Install\n\n```bash\ngit clone https://github.com/ThaiTrevor/gold-mcp.git\ncd gold-mcp\npip install -e .\n```\n\nPython 3.10+. No other setup, no env vars, no data files.\n\n### 2. Wire it into your MCP client\n\n#### Claude Desktop\n\nEdit `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows) or\n`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"gold-mcp\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"gold_mcp.server\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The tools appear under the plug icon.\n\n#### Claude Code (CLI)\n\n```bash\nclaude mcp add --scope user gold-mcp -- python -m gold_mcp.server\n```\n\n#### Cursor / Windsurf / Cline / Continue / Zed\n\n`~/.cursor/mcp.json` (or the equivalent file for your client):\n\n```json\n{\n  \"mcpServers\": {\n    \"gold-mcp\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"gold_mcp.server\"]\n    }\n  }\n}\n```\n\n#### ChatGPT Desktop / Agent mode\n\nSettings → Connectors → Add MCP server:\n\n```\nCommand: python\nArgs:    -m gold_mcp.server\n```\n\n### 3. Try it\n\nAsk the model in plain English. Examples:\n\n> \"What is gold doing right now and how does it compare to today's\n> macro tape (DXY, yields, VIX)?\"\n\n> \"Show me the last 24 hourly bars of gold and the 60-day correlation\n> with silver and DXY.\"\n\n> \"Give me a market snapshot for gold — combine price, macro context,\n> correlations, and the day-of-week seasonality.\"\n\n> \"USD/VND right now and the implied world-parity gold price in VND\n> per tael. If SJC is quoting 145 million, what's the premium?\"\n\n## Why this exists\n\nLLMs reason well about gold but they don't see live market data, the\nmacro tape that moves gold, or a clean correlation matrix on demand.\nThis server is a tiny, free bridge between an MCP client and the\npublic Yahoo Finance data that any researcher already has access to —\nexposed as well-typed tools so the model picks the right one\nautomatically.\n\nIt started as a study project to learn MCP architecture and turned\ninto something useful enough to publish for the community.\n\n## Upgrading to Pro / Premium\n\nAdd `GOLD_MCP_LICENSE_KEY` to the env block of your MCP config:\n\n```json\n\"env\": {\n  \"GOLD_MCP_LICENSE_KEY\": \"eyJ0aWVy...Ijoi.MEUCI...\"\n}\n```\n\nRestart your MCP client. Call `diagnostic` — `tier_active` should\nreport `pro` or `premium`. New tools become available immediately.\n\nSee [examples/claude_desktop_config_pro.json](examples/claude_desktop_config_pro.json)\nfor the full template.\n\n## Architecture\n\n```\ngold_mcp/\n  server.py            FastMCP wiring with 3-tier gating (21 tools max)\n  gold_data.py         yfinance price + OHLCV\n  macro_data.py        DXY/yields/SPX/VIX/BTC + correlations\n  analytics.py         seasonality\n  analyst.py           one-call aggregator (gold_market_snapshot)\n  cache.py             TTL filesystem cache (60s → 24h)\n  license.py           Ed25519 offline license verification\n  issue_license.py     CLI: init-keys, issue, verify\n  pro_tools.py         Pro tier: advanced TA, alerts, multi-timeframe\n  premium_tools.py     Premium tier: backtest, walk-forward, optimizer\n  adapters/\n    vn_macro.py        USD/VND + world-parity gold\n```\n\nFor vendors selling licenses, see the CLI:\n\n```bash\npython -m gold_mcp.issue_license init-keys\n# Paste printed PUBLIC_KEY_B64 into gold_mcp/license.py\n\npython -m gold_mcp.issue_license issue --tier pro --email u@x.com --days 30\n```\n\nOr run the Lemon Squeezy webhook handler (port from\n[mcp-byok-template](https://github.com/YOUR_GH/mcp-byok-template) —\nswap the env-var name from `MCP_BYOK_LICENSE_KEY` to `GOLD_MCP_LICENSE_KEY`).\n\n## Contributing\n\nThis project is small on purpose. We welcome contributions that fit\nthe same pattern:\n\n- Small, focused tools that wrap one public data source\n- Return structured JSON with named keys + a short interpretation field\n- No private data, no scraped credentials, no broker-specific paths\n- No tools that produce trading recommendations\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details and\n[SECURITY.md](SECURITY.md) for how to report security issues.\n\n## Testing\n\n```bash\npip install -e \".[dev]\"\npytest\n```\n\nCI runs the suite on Linux, macOS, and Windows across Python\n3.10/3.11/3.12 on every push and pull request.\n\n## Disclaimer\n\n`gold-mcp` is a data and analysis tool for educational and research\npurposes only. Nothing returned by any tool constitutes investment\nadvice, a recommendation, or a solicitation. Markets carry risk; you\nare responsible for your own decisions.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 9544,
  "sha": "2fa91ca255987567dea2e813698cbf0267b05bf7db9bc54f21963ef3f6af053b",
  "repo_slug": "thaitrevor/gold-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_thaitrevor_gold_mcp_c7d0051e/readme"
}