CommodityPriceAPI

CommodityPriceAPI MCP Server

[npm version] [GitHub] [Node.js] [License]

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.

2. Cursor users can install in one click:

   [Add to Cursor]

3. 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": "<YOUR_API_KEY>"      }    }  }}

4. Restart your client.

5. 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": "<YOUR_API_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:

[Add to Cursor]

Or add to .cursor/mcp.json manually:

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

Restart Cursor after saving.

Windsurf

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

{  "mcpServers": {    "commoditypriceapi": {      "command": "npx",      "args": ["-y", "@commoditypriceapi/mcp"],      "env": {        "COMMODITYPRICEAPI_KEY": "<YOUR_API_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": "<YOUR_API_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": "<YOUR_API_KEY>"      }    }  }}

Restart Cline after saving.

Codex CLI

codex mcp add commoditypriceapi --env COMMODITYPRICEAPI_KEY=<YOUR_API_KEY> -- npx -y @commoditypriceapi/mcpcodex 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": "<YOUR_API_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 latest prices for silver, platinum, copper, and WTI crude.
• What's gold trading at in euros?

Historical data

• What was the price of wheat on January 2nd, 2026?
• Compare gold and silver prices over the last 30 days.
• Show me daily natural gas prices for Q1 2026.

Intraday

• Show gold's hourly price on November 4th, 2026.
• Give me silver's 5-minute rates between 14:00 and 16:00 UTC yesterday.
• When did Brent crude peak during yesterday's session?

Price changes

• How much did Brent crude fluctuate this quarter?
• Did gold go up or down since the start of the year, and by how much?

Discovery and account

• Which commodity symbols do you support for energy?
• How much of my API quota is left this month?

Example Answers and Tool Output

The text answers show what a client might say; exact wording depends on the model. JSON blocks are raw tool output.

Latest gold price

Prompt: What's the current gold price?

Example answer: Gold (XAU) is currently trading at $4,386.23 per troy ounce (bid $4,385.93 / ask $4,386.23).

{  "success": true,  "timestamp": 1786617187,  "rates": {    "XAU": {      "rate": 4386.23,      "bid": 4385.93,      "ask": 4386.23    }  },  "metadata": {    "XAU": {      "unit": "T.oz",      "quote": "USD"    }  }}

Historical rate

Prompt: What was the gold price on January 2nd, 2020?

Example answer: On 2020-01-02, gold opened at $1,518.26 and closed at $1,528.76 per troy ounce (high $1,531.31, low $1,517.15).

{  "success": true,  "date": "2020-01-02",  "rates": {    "XAU": {      "date": "2020-01-02",      "open": 1518.26,      "high": 1531.31,      "low": 1517.15,      "close": 1528.76    }  }}

Intraday rates

Prompt: Show gold's hourly price on October 14th, 2026, from 18:00 UTC.

Example answer: Gold moved between $3,958.84 and $3,967.38 per troy ounce from 18:00 to 23:00 UTC, ending the day at its high of $3,967.38.

{  "success": true,  "symbol": "XAU",  "date": "2026-10-14",  "interval": "1h",  "startTime": "18:00",  "count": 6,  "nextStartTime": null,  "rates": {    "2026-10-14T18:00:00Z": 3961.27,    "2026-10-14T19:00:00Z": 3958.84,    "2026-10-14T20:00:00Z": 3963.1,    "2026-10-14T21:00:00Z": 3966.45,    "2026-10-14T22:00:00Z": 3964.92,    "2026-10-14T23:00:00Z": 3967.38  },  "metadata": {    "XAU": { "unit": "T.oz", "quote": "USD" }  }}

Fluctuation

Prompt: How much did gold change between January 2nd and August 12th, 2026?

Example answer: Gold rose from $4,332.01 to $4,400.12 per troy ounce — up $68.11, or +1.57%.

{  "success": true,  "startDate": "2026-01-02",  "endDate": "2026-08-12",  "rates": {    "XAU": {      "startRate": 4332.01,      "endRate": 4400.12,      "change": 68.11,      "changePercent": 1.57    }  }}

Auto-resolved symbol

Prompt: What's the price of GOLD and platinum?

Example answer: Gold (XAU) is $4,386.23 and platinum (XPT) is $1,412.50 per troy ounce. Note: GOLD isn't a symbol code, so the API returned it under XAU.

{  "success": true,  "timestamp": 1786617187,  "rates": {    "XAU": 4386.23,    "XPT": 1412.5  },  "metadata": {    "XAU": { "unit": "T.oz", "quote": "USD" },    "XPT": { "unit": "T.oz", "quote": "USD" }  },  "unresolved": {    "GOLD": {      "message": "GOLD is not a symbol code used by this API. Gold is available as \"XAU\", so its rate was returned under that symbol.",      "resolvedTo": "XAU"    }  }}

Status is 200 — an entry with resolvedTo never downgrades the response.

Error Codes

Tool calls never crash the server. Upstream errors are returned as structured tool results with error, code, message, and a guidance field so the client can explain what went wrong instead of echoing a status code.

Example error result for an invalid symbol:

{  "error": "SYMBOL_NOT_FOUND",  "code": 404,  "message": "The symbol is not supported, please visit the documentation for a list of supported symbols",  "guidance": "Call list_symbols to see valid commodity symbols."}

How It Works

This is a stdio MCP server that wraps the CommodityPriceAPI v3 REST API.

At runtime:

1. Your MCP client starts the server process via npx.
2. The client reads the tool list.
3. When a prompt matches a tool, the client calls it.
4. The server validates inputs, calls the CommodityPriceAPI, and returns structured JSON.

The server sends your API key to CommodityPriceAPI via both the x-api-key header and the apiKey query parameter — the upstream API accepts either, so this covers all cases without extra config.

Environment Variables

Building from Source

git clone https://github.com/Commodity-Price-API/commoditypriceapi-mcp.gitcd commoditypriceapi-mcpnpm installnpm run build

Run it directly:

COMMODITYPRICEAPI_KEY=<YOUR_KEY> node dist/cli.js

Inspect with the MCP Inspector:

COMMODITYPRICEAPI_KEY=<YOUR_KEY> npx @modelcontextprotocol/inspector node dist/cli.js

Troubleshooting

Client uses an old tool list after updating: Restart the client and confirm it loaded the latest npm version.

401 errors: Check that COMMODITYPRICEAPI_KEY is set in your MCP client config's env block.

A symbol is missing from a multi-symbol response: Look at the unresolved map in the result. If the entry has resolvedTo, nothing is missing — the rate is in rates under that symbol (e.g. GOLD → XAU, PL → XPT). Otherwise each missing symbol has a message and usually suggestions (e.g. OIL → WTIOIL-SPOT, BRENTOIL-SPOT, …). If there are no suggestions, call list_symbols to find the correct symbol.

499 timeouts: The upstream API did not respond in time. Increase COMMODITYPRICEAPI_REQUEST_TIMEOUT_MS (default: 15000 ms).

Pricing

Free 7-day trial with 2,000 requests, no card required. For plan details, see the CommodityPriceAPI pricing page.

Links

• CommodityPriceAPI Website
• API Documentation
• Supported Symbols
• MCP Integration Guide
• Pricing
• Sign Up Free
• GitHub Repository

License

MIT