GoldAPI.io MCP Server

Official Model Context Protocol server for GoldAPI.io precious metals data.

@goldapi/mcp-server lets MCP clients such as Claude Desktop, ChatGPT, Cursor, Windsurf, and other AI agent runtimes retrieve real-time and historical precious metals prices from GoldAPI and perform common bullion and jewelry value calculations.

Features

• Latest GoldAPI.io spot prices for gold, silver, platinum, and palladium.
• Historical GoldAPI prices by date.
• Metal value calculations by weight, unit, and purity.
• Supported currencies for major fiat currencies and BTC.
• Strict input validation with useful MCP errors.

Installation

npm install -g @goldapi/mcp-server

You can also run without global installation:

npx -y @goldapi/mcp-server

Environment

Create a GoldAPI API key from the GoldAPI dashboard and pass it as GOLDAPI_KEY.

GOLDAPI_KEY=your_api_key

If GOLDAPI_KEY is missing, the server exits with:

Missing GOLDAPI_KEY environment variable

Claude Desktop Configuration

Add this to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "goldapi": {
      "command": "npx",
      "args": ["-y", "@goldapi/mcp-server"],
      "env": {
        "GOLDAPI_KEY": "your_api_key"
      }
    }
  }
}

Cursor Setup

Add a new MCP server in Cursor settings:

{
  "mcpServers": {
    "goldapi": {
      "command": "npx",
      "args": ["-y", "@goldapi/mcp-server"],
      "env": {
        "GOLDAPI_KEY": "your_api_key"
      }
    }
  }
}

Windsurf Setup

Add the server to your Windsurf MCP configuration:

{
  "mcpServers": {
    "goldapi": {
      "command": "npx",
      "args": ["-y", "@goldapi/mcp-server"],
      "env": {
        "GOLDAPI_KEY": "your_api_key"
      }
    }
  }
}

Tools

get_metal_price

Get latest precious metal spot price.

Input:

{
  "metal": "XAU",
  "currency": "USD"
}

Output:

{
  "metal": "XAU",
  "currency": "USD",
  "price": 2391.72,
  "change": 11.6,
  "changePercent": 0.49,
  "timestamp": 1716000000
}

get_historical_metal_price

Retrieve historical metal price.

Input:

{
  "metal": "XAU",
  "currency": "USD",
  "date": "20250101"
}

Calls:

GET https://www.goldapi.io/api/{metal}/{currency}/{date}

calculate_metal_value

Calculate value of metal using weight and purity.

Input:

{
  "metal": "XAU",
  "currency": "AED",
  "weight": 125,
  "unit": "gram",
  "purity": "22k"
}

Output:

{
  "metal": "XAU",
  "metalName": "Gold",
  "currency": "AED",
  "weight": 125,
  "unit": "gram",
  "purity": "22k",
  "purityPercent": 91.67,
  "spotPricePerGram": 283.21,
  "adjustedPricePerGram": 259.57,
  "totalValue": 32446.25,
  "timestamp": 1716000000,
  "humanReadable": "The current estimated value of 125 grams of 22k gold is AED 32,446.25."
}

Supported units:

• gram
• kg
• oz
• troy_oz

Supported purities:

• 24k = 100%
• 22k = 91.67%
• 21k = 87.5%
• 20k = 83.33%
• 18k = 75%
• 16k = 66.67%
• 14k = 58.33%
• 10k = 41.67%

get_supported_metals

Returns:

["XAU", "XAG", "XPT", "XPD"]

get_supported_currencies

Returns all supported currencies.

Supported Metals

• XAU - Gold
• XAG - Silver
• XPT - Platinum
• XPD - Palladium

Supported Currencies

AED, AUD, BTC, CAD, CHF, CNY, CZK, EGP, EUR, GBP, HKD, INR, JOD, JPY, KRW, KWD, MXN, MYR, OMR, PLN, RUB, SAR, SGD, THB, USD, ZAR

Example Prompts

What is gold price in AUD?

What is current value of 125 grams of 22k gold in AED?

What was gold price in USD on January 1st 2025?

What is value of 3 troy ounces of silver?

Local Development

npm install
npm run build
npm run verify

Run the server locally:

GOLDAPI_KEY=your_api_key npm run dev

Run the built server:

GOLDAPI_KEY=your_api_key npm start

Publishing

npm publish --access public