commodity-mcp

Commodity pricing data in any MCP client. Ask an AI assistant what copper has done over twenty years, when a material is usually cheapest, or what the 1973 embargo did to steel costs — and have it build you a dashboard you can open in the browser.

This is the MCP server for ScrapeMonk Commodity. It holds no data and no credentials of its own: every call is made as the signed-in user, against their own account.

Install

Add it to your client's MCP configuration:

{
  "mcpServers": {
    "commodity-data": {
      "command": "npx",
      "args": ["-y", "commodity-mcp"]
    }
  }
}

Then run the login tool. It opens a browser for an Auth0 sign-in and caches the result in ~/.commodity-data/token.json.

Access needs a Commodity seat in Wistery Admin. Without one the tools say what is missing (an account, an organization or a seat) rather than failing with something cryptic, and where your organization can give you a seat, they give you the link to request it.

What it can do

Prices and analysis

| Tool | | | --- | --- | | get_prices | The price series itself, so you can compute trends and correlations — not just a summary. Defaults to 20 years; long daily series are averaged by month or year to fit, and the answer says which. Can list the events in the same window, and links to the chart in the web app. | | get_seasonality | How a commodity moves through the year: per-month average, range and spread, plus the seasonal effect with the trend removed. It names a cheapest and a dearest month only when the months observed differ by more than chance. Works for your uploads too, and links to the charts in the web app. | | list_events | Over a hundred events from 1972 onward, each with a written account of what it did to which commodities. Narrow by date window, or find the events that mention a commodity by its plain name (oil, copper, wheat). | | list_commodities, search_commodities | The catalogue — 180+ indices across metals, energy, polymers, agriculture, FX and economic indicators. |

Your own data

| Tool | | | --- | --- | | import_prices | Upload your own series as CSV — contracted buy prices, a supplier quote, an internal index — to sit on a dashboard beside market data. The answer says which columns were read and which rows were left out; importing again under the same name replaces your series, and a colleague's only when asked to. Visible to you and your organization, never sent to any provider. | | delete_commodity | Delete an upload, for everyone in your organization. The answer says whose it was and which of the dashboards you can see still list it. |

Dashboards

list_dashboards, create_dashboard, update_dashboard, delete_dashboard. A dashboard is private to you, or shared with your whole organization, whose members can then see and edit it. Creating or updating one answers with a link that opens it in the browser.

Data sources

list_connectors, connect_source, disconnect_source. A source is off until you, or someone in your organization, turns it on, and enabling one accepts that provider's terms on your behalf — so connect_source shows you the terms first and enables only once you have agreed. Some providers need an API key of your own or your organization's.

Session and admin

login, logout, whoami. search_fred searches FRED's catalogue for series not yet carried, using your FRED key or one stored by someone in your organization. list_users is for TopMonks admins.

search_yfinance is currently unavailable and says so.

Where the data comes from

Seven providers — Yahoo Finance, FRED, ECB, EIA, BLS, Eurostat and the World Bank — each opt-in. There are no platform-owned API keys: a source is on once you or someone in your organization enables it, with the key that person stored where a provider requires one, unless you have switched it off for yourself.

Where a series is assembled from more than one provider, the answer names all of them, oldest layer last (yfinance+eia+worldbank), and carries the credit each one's terms require.

Configuration

Everything has a working default; override only what you need.

| Variable | Default | | | --- | --- | --- | | MCP_API_URL | https://app.commodity.scrapemonk.io | The Commodity web app, which serves the API too; answers link into it | | MCP_AUTH0_DOMAIN | wistery.eu.auth0.com | Auth0 tenant | | MCP_AUTH0_CLIENT_ID | built in | Auth0 client | | MCP_AUTH0_AUDIENCE | built in | Auth0 API audience | | MCP_AUTH_CALLBACK_PORT | 18776 | Local port the sign-in returns to | | MCP_WISTERY_ADMIN_URL | production Admin, for the production API | Where a user without a seat is sent | | MCP_API_TIMEOUT_MS | 30000 | Per-request timeout |

Shared API keys are not supported: they bypassed the entitlement gate and could not be revoked per organization. Personal login is the only way in.

Reference

Every tool is documented with its full argument schema in mcp/openapi-v1.html in the Commodity repository; the tools, their arguments and descriptions are generated from the server's own tool list. Ask your TopMonks contact if you need a copy.

whoami is the quickest check that everything is wired up: it reports who you are signed in as, your organization, and whether your account can use Commodity.

Licence

Commercial. Access is governed by the customer agreement.