Docs / MCP server

Gold Price MCP Server

MCP on every plan, including Free. Nine tools, 30-second setup in Claude Desktop or Cursor. Forward view: Legacy plans only.

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_..." }
    }
  }
}

// Ctrl/Cmd-Shift-P → "Restart MCP servers"
# 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.

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.

Tier	Rate limit	Symbol scope	Tools available
Free	10 / min	XAU + XAG + HG spot	All 9 listed · paid products gated
Basic	60 / min	XAU + XAG + HG spot · dealer prices	All 9 listed
Plus	120 / min	XAU + XAG + HG spot · dealer prices	All 9 listed
Pro	300 / min	XAU + XAG + HG spot · dealer prices	All 9 listed

Troubleshooting

Claude doesn't see the tools?

Fully quit Claude (Cmd-Q, not just close the window) and reopen. MCP servers load once, on launch. If the icon still shows "0 tools", check that the config JSON parses. A trailing comma is the usual culprit.

Getting "invalid_api_key"?

Make sure GP_KEY is set in the env block, not the shell. Claude Desktop doesn't inherit your terminal's environment. It reads config JSON literally.

Still stuck? Email hello@goldprice.dev.