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 and keeps the candle DB bounded.

HTTP

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

Tools

• get_price
• get_ohlcv
• get_last_candle
• get_market_snapshot
• get_indicator
• get_top_movers
• get_capabilities
• get_regime

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.
• 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