metals-mcp

Metals MCP Server

FastMCP-based metals market data server backed by a Swissquote poller and local candle store.

Transport

• MCP SSE transport mounted at /mcp
• SSE stream endpoint: /mcp/sse
• message endpoint handled by FastMCP under /mcp/messages/
• no legacy /rpc compatibility path

Runtime

source .venv/bin/activate
pip install -r requirements.txt
./run.sh

Default URL base: http://127.0.0.1:8515

Docker / Compose

docker compose up -d --build

The compose file persists data/ and logs/ into the project directory, binds the server to 0.0.0.0, and keeps the candle DB bounded. Reload is off by default in container runs, so the poller won't trigger watcher loops.

HTTP

• GET / → health + tool list
• GET /health → health + cache/store stats

Tools

• get_price - Fetch live Swissquote quotes for metals
• get_ohlcv - Get OHLCV candle data for a symbol and timeframe
• get_last_candle - Get the most recent completed candle
• get_market_snapshot - Get comprehensive market analysis for a single symbol (price, trend, regime, etc.)
• get_indicator - Calculate technical indicators (SMA, EMA, RSI, ATR, return_pct, volatility)
• get_top_movers - Get top moving symbols by percentage change
• get_capabilities - Get server capabilities and available tools
• get_regime - Get market regime classification (bullish, bearish, compression, neutral)
• get_snapshot - Get comprehensive multi-timeframe, multi-symbol market snapshot with cross-asset analysis

Notes

Done

• Shared MCP surface mirrors crypto-mcp tool names, with get_last_candle kept as a small metals-specific convenience.
• get_price fetches live Swissquote quotes for metals like XAU.
• An internal background poller keeps the server self-sufficient.
• 5m candles are clock-aligned and persisted in SQLite for XAU/USD, XAG/USD, XPT/USD, and XPD/USD by default.
• get_market_snapshot and get_regime now provide the useful metals context in crypto-style naming.
• get_snapshot provides comprehensive multi-timeframe, multi-symbol analysis with cross-asset insights.
• Candle retention is bounded by METALS_CANDLE_RETENTION_DAYS (default 30), with periodic pruning to keep the DB bounded.

Planned

• Keep refining get_indicator, get_market_snapshot, get_top_movers, and get_regime as more metals behavior becomes useful to Argus.
• Add retention cleanup for older candles.
• Expand the watched pair set only if it proves useful for market orientation.

Design

• The public surface should mirror crypto-mcp where practical.
• Local default port is 8515.
• Under the hood, the server uses Swissquote polling plus a local candle store.
• The repo now contains a working scaffold and the first live price path.

Verification

./tests.sh
./run.sh

Housekeeping

• ./killserver.sh stops stale listeners on the configured port
• ./restart.sh chains kill and run