CommodityPriceAPI

CommodityPriceAPI MCP Server

Official MCP server for CommodityPriceAPI. Exposes 9 MCP tools for real-time, intraday and historical commodity prices — gold, silver, oil, natural gas, wheat, coffee, and 140+ other commodities. Your AI assistant queries the market in plain English; the MCP server handles the API calls.

Works with Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Cline, Codex, and any other MCP-compatible client.

Quick Start

1. Get a free CommodityPriceAPI key — free 7-day trial, 2,000 requests, no card required.

1. Cursor users can install in one click:

1. Everyone else: add this to your MCP client config (see Install by Client for the exact file path):

{

"mcpServers": { "commoditypriceapi": { "command": "npx", "args": ["-y", "@commoditypriceapi/mcp"], "env": { "COMMODITYPRICEAPI_KEY": " " } } } }

1. Restart your client.

1. Test it: ask "What's the current gold price?"

Table of Contents

• Quick Start
• Install by Client
• Verify It Works
• Tool Reference
• Prompt Examples
• Example Answers and Tool Output
• Error Codes
• How It Works
• Environment Variables
• Building from Source
• Troubleshooting
• Pricing
• Links
• License

Install by Client

Requirements

• Node.js 18 or later
• npx available in your terminal
• A CommodityPriceAPI key — sign up free

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{

"mcpServers": { "commoditypriceapi": { "command": "npx", "args": ["-y", "@commoditypriceapi/mcp"], "env": { "COMMODITYPRICEAPI_KEY": " " } } } }

Restart Claude Desktop after saving.

Claude Code

claude mcp add commoditypriceapi --env COMMODITYPRICEAPI_KEY=<YOUR_API_KEY> -- npx -y @commoditypriceapi/mcp

Start a new Claude Code session after adding the server.

Cursor

One-click install:

Or add to .cursor/mcp.json manually:

{

"mcpServers": { "commoditypriceapi": { "command": "npx", "args": ["-y", "@commoditypriceapi/mcp"], "env": { "COMMODITYPRICEAPI_KEY": " " } } } }

Restart Cursor after saving.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{

"mcpServers": { "commoditypriceapi": { "command": "npx", "args": ["-y", "@commoditypriceapi/mcp"], "env": { "COMMODITYPRICEAPI_KEY": " " } } } }

Restart Windsurf after saving.

VS Code / GitHub Copilot

Add to your VS Code settings.json:

{

"mcp": { "servers": { "commoditypriceapi": { "command": "npx", "args": ["-y", "@commoditypriceapi/mcp"], "env": { "COMMODITYPRICEAPI_KEY": " " } } } } }

Restart VS Code after saving.

Cline

Open MCP Servers panel → Configure → Advanced MCP Settings. Add to cline_mcp_settings.json:

{

"mcpServers": { "commoditypriceapi": { "command": "npx", "args": ["-y", "@commoditypriceapi/mcp"], "env": { "COMMODITYPRICEAPI_KEY": " " } } } }

Restart Cline after saving.

Codex CLI

codex mcp add commoditypriceapi --env COMMODITYPRICEAPI_KEY=<YOUR_API_KEY> -- npx -y @commoditypriceapi/mcp

codex mcp list

Start a new Codex session after adding the server.

Any Other MCP Client

Use this config:

{

"command": "npx", "args": ["-y", "@commoditypriceapi/mcp"], "env": { "COMMODITYPRICEAPI_KEY": " " } }

Verify It Works

Try these after setup:

Tool Reference

All 9 tools map 1:1 to CommodityPriceAPI v3 endpoints. Tools that take symbols accept a comma-separated list; get_intraday_rates takes a single symbol (e.g. XAU,XAG,XPT,BRENTOIL-SPOT). Use list_symbols to look up valid symbols — there are 245 across Metals, Energy, Agriculture, and more.

Precious metals use ISO 4217 codes: XAU (gold), XAG (silver), XPT (platinum), XPD (palladium). Copper is XCU. The retired codes PL, PA, and HG still work on v3 — they are auto-resolved to the new symbol (see the note below).

get_latest_rates

GET /v3/rates/latest — latest rates for one or more symbols. Rates may lag up to 10 minutes depending on plan.

Note on unresolved: v3 appends an unresolved map, keyed by the symbol you typed, in three cases. The same applies to get_intraday_rates, get_historical_rates, get_time_series, and get_fluctuation.

get_gold_price

GET /v3/rates/latest/xau — shortcut for the latest gold (XAU) rate, including bid/ask.

get_silver_price

GET /v3/rates/latest/xag — shortcut for the latest silver (XAG) rate, including bid/ask.

get_intraday_rates

GET /v3/rates/intraday — the rates of one symbol through a single UTC day at a chosen interval, from one minute to one day. Each point is the rate recorded at that exact mark (14:05 is the rate observed at 14:05 UTC), not an OHLC bar. Advanced and Enterprise plans only — other plans get 402.

A result holds at most 100 points. When nextStartTime is not null, call again with startTime set to it to get the next page; from 15m upward a whole day fits in one call. Marks with no recorded rate are left out, so count can be below the window size. Only symbols updated every second, minute, or 10 minutes have intraday data — others return 400 BAD_REQUEST. Rates are in the symbol's own currency; there is no quote parameter.

get_historical_rates

GET /v3/rates/historical — open/high/low/close rates for one or more symbols on a specific past date, available back to 1990-01-01. If no rate exists for that exact date, the API returns the nearest available date.

get_time_series

GET /v3/rates/time-series — daily historical rates for one or more symbols between two dates. Max span: 1 year.

get_fluctuation

GET /v3/rates/fluctuation — how each symbol changed between two dates: start rate, end rate, absolute change, and percent change.

list_symbols

GET /v3/symbols — all supported commodity symbols with name, category, quote currency, unit, and update interval. Takes no parameters. Call this before rate tools when unsure of a symbol.

get_usage

GET /v3/usage — current plan, quota, and usage for the configured API key. Takes no parameters.

Prompt Examples

Live prices

• What's the current gold price?
• What's gold per gram right now?
• Get the