Gold Price MCP Server

Why MCP

Model Context Protocol lets an LLM call your tools directly, with native schemas the model can reason about. When a user asks Claude "what's gold in rupees per gram today?", MCP lets Claude call get_spot_price with the right arguments instead of guessing.

We expose nine tools, all thin wrappers around the REST endpoints you already know. Same auth, same rate limits, same staleness semantics, just structured for agent use.

Install in 30 seconds

Pick your path. Global install gives you a local mcp binary and skips the per-launch npm download; the npx variant in the Claude Desktop + Cursor panes works with zero prior setup.

# One-time global install
npm install -g @nusantara-ventures/goldprice-mcp

# Then reference the installed binary in your MCP client config:
#   "command": "mcp"   (not "npx")

# Verify it's on PATH:
which mcp

# Edit ~/Library/Application Support/Claude/claude_desktop_config.json
# (on Windows: %APPDATA%\Claude\claude_desktop_config.json)
{
  "mcpServers": {
    "goldprice": {
      "command": "npx",
      "args": ["-y", "@nusantara-ventures/goldprice-mcp"],
      "env": {
        "GP_KEY": "ga_live_a94f…2c71"
      }
    }
  }
}

# Restart Claude. The icon should show "goldprice" with the tools available on your plan.

// .cursor/mcp.json at repo root or ~/.cursor/mcp.json
{
  "mcpServers": {
    "goldprice": {
      "command": "npx",
      "args": ["-y", "@nusantara-ventures/goldprice-mcp"],
      "env": { "GP_KEY": "ga_live_..." }
    }
  }
}

// After editing mcp.json, restart Cursor or switch the server off and on under Customize.

# Any MCP client: point it at the stdio server directly
npx -y @nusantara-ventures/goldprice-mcp

# Environment variables:
#   GP_KEY       required: your API key
#   GP_BASE_URL  optional: defaults to https://api.goldprice.dev
#   GP_TIMEOUT   optional: ms, defaults to 10000

Available tools

All nine tools are listed on every plan. XAU, XAG, and HG spot are included on every plan. Daily history is 30 days on Free, one year on Basic, and full on Plus and Pro. Plus has 1h and 4h bars for the last 30 days; Pro has 1m, 5m, 15m, 30m, 1h, 2h, and 4h bars at full depth. Dealer prices require Basic+. Futures are Legacy plans only.

• start_checkout: human-confirmed billing handoff for Basic, Plus, or Pro. Free accounts receive a one-hour Checkout URL; existing subscribers open billing management. Cancelling creates nothing.
• get_spot_price: latest spot price for one symbol (GC futures: Legacy plans only). "What's gold trading at right now in INR?" Symbol scope per tier.
• list_commodities: catalog of supported symbols. Call this first when you don't know the valid symbol for a currency or contract.
• get_metadata: per-symbol provenance: sources, unit, staleness rules, methodology URL, commercial-use notes. Use for attribution and data-lineage documentation.
• get_carat: per-gram gold (XAU) price by karat purity (24k…10k) in any of 35 currencies. It is free on every tier, with no plan gate. Same math as /v1/carat.
• get_historical: OHLCV bars between two dates. Default 1d. Daily: Free 30 days, Basic one year, Plus/Pro full. Plus: 1h/4h for 30 days. Pro: 1m, 5m, 15m, 30m, 1h, 2h, 4h at full depth.
• search_docs: BM25 search over the bundled FAQ corpus. Use before answering how-to / billing / auth questions so you cite canonical text instead of guessing.
• get_forward_view: Legacy plans only. Futures settlement curve, populated horizons up to 12 months out.
• get_physical_price: real dealer/retail gold prices for one country (ISO alpha-2 code), each quote carrying premium_over_spot_bps. Basic+; static sample responses at /docs/physical for evaluation without a paid key.

At https://api.goldprice.dev/v1/mcp/ get_spot_price, list_commodities, get_carat, search_docs, get_metadata and get_historical answer without an API key. Prices are delayed 15 minutes, matching the Free plan. Without a key, get_physical_price and get_forward_view return a plan_gated error: get_physical_price needs Basic or above, while get_forward_view is available only on legacy plans. start_checkout needs an API key and returns api_key_required without one. get_historical gives 30 days of daily history without a key; longer history needs a paid plan.

Rate limits per tier

MCP calls share the same per-key rate limit as REST. Heavy agent usage (think: scripted backtests in a loop) lives on Pro; interactive chat fits comfortably in Basic.

Troubleshooting

Still stuck? Email hello@goldprice.dev.