CommodityPriceAPI MCP Server
Connect Claude, Cursor, Windsurf, VS Code, Cline, Codex, and any MCP-compatible client to real-time and historical commodity prices — gold, silver, oil, natural gas, wheat, coffee, and 140+ more. Your AI assistant queries the market in plain English; the MCP server handles the API calls.
Quick start
Up and running in three steps.
Get a free API key
Sign up for a free 7-day trial — 2,000 requests, no card required — and copy your API key from the dashboard.
Add one config block
Paste the commoditypriceapi server block into your MCP client's config. It runs via npx — nothing to install or host.
Ask in plain English
Restart your client and ask: "What's the current gold price?" Your AI assistant calls the API for you.
Set up your client
The same server works in every MCP client — only the config file location differs. Requirements: Node.js 18+, npx in your terminal, and an API key.
Add the block below to claude_desktop_config.json (Settings → Developer → Edit Config), then restart Claude Desktop.
claude_desktop_config.json
Replace <YOUR_API_KEY> with the key from your dashboard.
Verify it works
After setup, try these prompts — each one should trigger the tool listed next to it.
| Prompt | Expected tool |
|---|---|
| "What's the current gold price?" | get_gold_price |
| "Get the latest silver and Brent crude prices." | get_latest_rates |
| "What was the gold price on January 2nd, 2020?" | get_historical_rates |
| "Show daily gold prices for the first week of August 2026." | get_time_series |
| "How much did gold change between January and August 2026?" | get_fluctuation |
| "Which commodity symbols do you support?" | list_symbols |
| "How much of my API quota is left?" | get_usage |
Tool reference
8 tools, the full API surface — every CommodityPriceAPI v2 endpoint is exposed as an MCP tool your assistant can call. Parameters marked * are required.
| Tool | Endpoint | Parameters | What it does |
|---|---|---|---|
get_latest_rates | /v2/rates/latest | symbols*, quote | Latest rates for one or more symbols. Rates may lag up to 10 minutes depending on plan. |
get_gold_price | /v2/rates/latest/xau | quote | Shortcut for the latest gold (XAU) rate, including bid/ask. |
get_silver_price | /v2/rates/latest/xag | quote | Shortcut for the latest silver (XAG) rate. |
get_historical_rates | /v2/rates/historical | symbols*, date* | Open/high/low/close rates on a specific past date, back to 1990-01-01. Returns the nearest available date if none exists for the exact date. |
get_time_series | /v2/rates/time-series | symbols*, startDate*, endDate* | Daily historical rates between two dates. Maximum span: 1 year. |
get_fluctuation | /v2/rates/fluctuation | symbols*, startDate*, endDate* | How each symbol changed between two dates: start rate, end rate, absolute change, and percent change. |
list_symbols | /v2/symbols | — | All 148 supported symbols with name, category, quote currency, unit, and update interval. Call this before rate tools when unsure of a symbol. |
get_usage | /v2/usage | — | Current plan, quota, and usage for the configured API key. |
symbolstakes a comma-separated list, e.g.XAU,XAG,BRENTOIL-SPOT. There are 148 symbols across Metals, Energy, Agriculture, and more — see the full list of supported symbols.- If a symbol in a multi-symbol request is invalid, the API silently omits it from the response rather than returning an error. A missing symbol means the symbol is wrong — check
list_symbols. quoteconverts rates to a target currency (e.g.EUR) and is available on Premium/Plus plans only; omit it for each symbol's default currency.- Dates use
YYYY-MM-DDformat.
Example prompts & output
Things you can ask — anything the API can answer, your assistant can answer.
Live prices
- "What's the current gold price?"
- "Get the latest prices for silver, 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."
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 & account
- "Which commodity symbols do you support for energy?"
- "How much of my API quota is left this month?"
What the tool returns
Ask "What's the current gold price?" and get_gold_price returns structured JSON your assistant turns into a plain-English answer — e.g. "Gold (XAU) is currently trading at $4,386.23 per troy ounce (bid $4,385.93 / ask $4,386.23)."
Tool output
Error codes
Tool calls never crash the server. Upstream errors come back as structured results with error, code, message, and a guidance field, so your assistant can explain what went wrong instead of echoing a status code.
| Code | Meaning |
|---|---|
401 | Missing or invalid API key — check COMMODITYPRICEAPI_KEY in your client config. |
402 | Your trial or subscription doesn't cover this request (e.g. quote conversion on a non-Premium plan). |
403 | API key usage limit reached — upgrade or wait for quota reset. |
404 | Symbol not found — call list_symbols for valid symbols. |
429 | Rate limited — wait a minute and retry. |
499 | Request to the upstream API timed out (see COMMODITYPRICEAPI_REQUEST_TIMEOUT_MS). |
502 | Server could not reach the upstream API. |
Example error result for an invalid symbol:
Error result
Environment variables
Set these in the env block of your MCP client config.
| Variable | Required | Default | Description |
|---|---|---|---|
COMMODITYPRICEAPI_KEY | Yes | — | Your CommodityPriceAPI key. |
COMMODITYPRICEAPI_REQUEST_TIMEOUT_MS | No | 15000 | Upstream request timeout in milliseconds. |
Troubleshooting
The most common issues and their fixes. Still stuck? Contact support or open an issue on GitHub.
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
The upstream API silently drops invalid symbols instead of erroring. Call list_symbols to find the correct symbol — e.g. Brent crude is BRENTOIL-SPOT, not BRENTOIL.
499 timeouts
The upstream API did not respond in time. Increase COMMODITYPRICEAPI_REQUEST_TIMEOUT_MS (default: 15000 ms).