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 240+ 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 v3 endpoint is exposed as an MCP tool your assistant can call. Parameters marked * are required.
| Tool | Endpoint | Parameters | What it does |
|---|---|---|---|
get_latest_rates | /v3/rates/latest | symbols*, quote | Latest rates for one or more symbols. Rates may lag up to 10 minutes depending on plan. |
get_gold_price | /v3/rates/latest/xau | quote, include | Shortcut for the latest gold (XAU) rate, including bid/ask. include=gram, tola or carat adds a per-gram, per-tola or per-carat breakdown next to the troy-ounce rate. |
get_silver_price | /v3/rates/latest/xag | quote, include | Shortcut for the latest silver (XAG) rate, including bid/ask. include=gram, tola or carat adds a per-gram, per-tola or per-carat breakdown next to the troy-ounce rate. |
get_historical_rates | /v3/rates/historical | symbols*, date* | Open/high/low/close rates on a specific past date, back to 1990-01-01. If no rate exists for the exact date, the most recent earlier rate is returned together with its own date. |
get_time_series | /v3/rates/time-series | symbols*, startDate*, endDate* | Daily historical rates between two dates. Maximum span: 1 year. |
get_fluctuation | /v3/rates/fluctuation | symbols*, startDate*, endDate* | How each symbol changed between two dates: start rate, end rate, absolute change, and percent change. |
list_symbols | /v3/symbols | — | All 240+ supported symbols with name, category, quote currency, unit, and update interval. Call this before rate tools when unsure of a symbol. |
get_usage | /v3/usage | — | Current plan, quota, and usage for the configured API key. |
symbolstakes a comma-separated list, e.g.XAU,XAG,BRENTOIL-SPOT. There are 240+ symbols across Metals, Energy, Agriculture, and more — see the full list of supported symbols.- Symbols that cannot be returned are never dropped silently. The result includes an
unresolvedmap keyed by the symbol you sent: asuggestionslist for ambiguous or unknown codes (HTTP 206, the valid rates are still inrates), orresolvedTowhen a code had exactly one match, e.g.GOLDis answered asXAU(HTTP 200). If nothing resolves, the tool returns aSYMBOL_NOT_FOUNDerror carrying the same map. quotereturns the rate in the currency you want. Ask "What is the gold price in euros?" and the assistant passesquote=EUR, so the rate comes back in EUR. Without it, each symbol is returned in its default currency. Available on Premium and Plus plans; the Lite plan ignores it and return the default quote for each symbol.- 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, a guidance field and, for symbol errors, the unresolved map, so your assistant can explain what went wrong instead of echoing a status code. Partial results (HTTP 206) are not errors: they arrive as normal results with the valid rates plus unresolved.
| Code | Meaning |
|---|---|
400 | VALIDATION_ERROR — a required parameter is missing, a date is not in YYYY-MM-DD format, the start date is after the end date, a time-series range exceeds 365 days, or include is not gram, tola or carat. |
401 | UNAUTHORIZED — no API key was sent. Check that COMMODITYPRICEAPI_KEY is set in your client config's env block. |
402 | PAYMENT_REQUIRED — your trial has ended, your subscription is inactive, or the request asks for more symbols than your plan allows per request. |
403 | LIMIT_REACHED — monthly request quota used up. Upgrade or wait for the quota to reset. |
404 | USER_NOT_FOUND — the API key is invalid. SYMBOL_NOT_FOUND — none of the requested symbols resolved; the result carries an unresolved map with suggestions. QUOTE_NOT_FOUND — unsupported quote currency. RATE_NOT_FOUND / DATA_NOT_FOUND — the symbols are valid but have no data for that date or range. |
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 UNAUTHORIZED or 404 USER_NOT_FOUND
401 means no key reached the API: check that COMMODITYPRICEAPI_KEY is set in your MCP client config's env block. 404 USER_NOT_FOUND means a key was sent but it is not valid: copy it again from your dashboard.
A symbol you asked for is missing from the response
Look at the unresolved map in the result; it is keyed by the symbol you sent. An entry with suggestions means the code was ambiguous or unknown — pick one of the suggested symbols, e.g. BRENTOIL-SPOT for Brent crude. An entry with resolvedTo means the rate was returned under that symbol instead. An entry saying the symbol is supported but has no rate means there is no data for that request. Call list_symbols to browse valid codes.
499 timeouts
The upstream API did not respond in time. Increase COMMODITYPRICEAPI_REQUEST_TIMEOUT_MS (default: 15000 ms).