Docs / MCP server

Gold Price MCP Server

Wire gold prices directly into Claude Desktop, Cursor, or any MCP-compatible agent. Eight tools, 30-second setup, available on every plan — including Free.

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 eight 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 @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", "@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", "@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 @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 eight tools are listable and callable at every tier. Per-symbol scope follows your plan tier and is enforced by the REST API underneath — e.g. Free can invoke get_spot_price with XAG-USD-SPOT but the underlying response returns 403 plan_gated because silver is Pro-gated. The one inline MCP-level gate is get_historical: Free sees the last 30 days; Physical sees the last year; Pro unlocks the full history window.

get_spot_price— latest aggregated spot (or GC futures) price for one symbol. "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 31 currencies. Free on every tier — no plan gate. Same math as /v1/carat.
get_historical — daily OHLCV bars between two dates. Free limited to last 30 days; Physical to 1 year; Pro unlocks full history.
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 — multi-horizon forward view: the futures settlement curve, every populated horizon up to 12 months out. XAU on every tier; XAG/HG require Pro+.
get_physical_price — real dealer/retail gold prices for one country (ISO alpha-2 code), each quote carrying premium_over_spot_bps. Physical tier and above; 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 Physical.

Tier	Rate limit	Symbol scope	Tools available
Free	30 / min	XAU spot · 31 currencies	All 8 listed · paid products gated
Physical	120 / min	XAU spot + futures + physical dealer prices	All 8 listed
Pro	500 / min	XAU + XAG spot + futures · HG futures · physical	All 8

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