Primary Source Commodities

Official11 tools

by sawftware-apps

Primary-source commodities data for AI agents — EIA, FRED, CFTC, USDA, USGS via x402 on Base.

io.github.sawftware-apps/commodities-sh Model Context Protocol (MCP) Server

This MCP server provides “Primary-source commodities data for AI agents.” The server description specifies that it serves commodities data sourced from EIA, FRED, CFTC, USDA, and USGS, accessed via “x402 on Base.”

🛠️ Key Features

Delivers primary-source commodities data
Data sources: EIA, FRED, CFTC, USDA, USGS
Access method: x402 on Base
Implements 11 tools (toolCount: 11)

🚀 Use Cases

Supplying AI agents with commodities datasets from the listed primary sources

⚡ Developer Benefits

Centralizes multi-source commodities data access for AI workflows on Base
Exposes a tool set (11 tools) for integration

⚠️ Limitations

Only explicitly described as commodities data access via x402 on Base; no additional scope is provided

Captured live from the server via tools/list.

catalog.list

List every commodity instrument in the catalog with sector, unit, primary source, and freshness metadata. Call this first to discover valid codes before price.latest or inventory.get. Free discovery tool — no payment required.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

price.latest

Return the latest cash/fundies observation for one instrument code. Use catalog.list to discover codes such as CL, GC, or ZC. Response follows the shared observation contract with provenance and license tags.

Parameters1

code

string

required

Instrument code from catalog.list. Example: CL, GC, ZC.

Raw schema

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Instrument code from catalog.list. Example: CL, GC, ZC."
    }
  },
  "required": [
    "code"
  ],
  "additionalProperties": false
}

inventory.get

Fetch EIA weekly petroleum inventory levels. Omit series to list all latest inventory points, or pass a series key to get week-over-week change, vs-5y deviation, and a surprise label for that series.

Parameters1

series

string

optional

Optional EIA inventory series key. Omit to return all latest inventory rows. Example: crude_stocks.

Raw schema

{
  "type": "object",
  "properties": {
    "series": {
      "type": "string",
      "description": "Optional EIA inventory series key. Omit to return all latest inventory rows. Example: crude_stocks."
    }
  },
  "additionalProperties": false
}

positioning.get

Return the latest CFTC Commitments of Traders managed-money positioning for an instrument code. Includes long, short, net, and week-over-week net change with source URL.

Parameters1

code

string

required

Instrument code from catalog.list. Example: CL, NG, GC, ZC.

Raw schema

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Instrument code from catalog.list. Example: CL, NG, GC, ZC."
    }
  },
  "required": [
    "code"
  ],
  "additionalProperties": false
}

spread.get

Compute a derived spread observation: 3-2-1 crack, soybean crush, WTI-Brent basis, or calendar (calendar requires licensed curve data and may return available=false). Prefer crack/crush/basis for live derived values with formula and inputs.

Parameters2

type	string	required	Spread type to compute. Example: crack for 3-2-1 gasoline/distillate crack.
root	string	optional	Optional root symbol for calendar spreads. Example: CL. Ignored for crack/crush/basis.

Raw schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "crack",
        "crush",
        "basis",
        "calendar"
      ],
      "description": "Spread type to compute. Example: crack for 3-2-1 gasoline/distillate crack."
    },
    "root": {
      "type": "string",
      "description": "Optional root symbol for calendar spreads. Example: CL. Ignored for crack/crush/basis."
    }
  },
  "required": [
    "type"
  ],
  "additionalProperties": false
}

price.history

Return historical observations for an instrument code (up to 500 points). Use after price.latest when you need a short time series for the same code.

Parameters2

code	string	required	Instrument code from catalog.list. Example: CL, GC, ZC.
limit	number	optional	Number of historical points to return. Max 500, default 60.

Raw schema

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Instrument code from catalog.list. Example: CL, GC, ZC."
    },
    "limit": {
      "type": "number",
      "description": "Number of historical points to return. Max 500, default 60."
    }
  },
  "required": [
    "code"
  ],
  "additionalProperties": false
}

fx.latest

Return the latest FX rate observation for a pair or FRED FX series. Useful alongside commodity prices when converting cash values across currencies.

Parameters1

pair

string

required

FX pair or series id. Example: EURUSD, USDCNY, DTWEXBGS.

Raw schema

{
  "type": "object",
  "properties": {
    "pair": {
      "type": "string",
      "description": "FX pair or series id. Example: EURUSD, USDCNY, DTWEXBGS."
    }
  },
  "required": [
    "pair"
  ],
  "additionalProperties": false
}

fundamentals.get

Fetch a fundamentals document: USDA WASDE, crop progress, export sales, or USGS mineral summaries. Choose kind based on the ags/metals question you are answering.

Parameters1

kind

string

required

Fundamentals report kind. Example: wasde for World Agricultural Supply and Demand Estimates.

Raw schema

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "wasde",
        "crop_progress",
        "export_sales",
        "usgs"
      ],
      "description": "Fundamentals report kind. Example: wasde for World Agricultural Supply and Demand Estimates."
    }
  },
  "required": [
    "kind"
  ],
  "additionalProperties": false
}

snapshot.get

Build a sector snapshot bundling prices, inventories, spreads, and related fundies for energy, metals, ags, or all sectors. Prefer this over calling many single-observation tools when you need a full sector picture.

Parameters1

sector

string

required

Sector to snapshot. Use all to receive energy, metals, and ags together.

Raw schema

{
  "type": "object",
  "properties": {
    "sector": {
      "type": "string",
      "enum": [
        "energy",
        "metals",
        "ags",
        "all"
      ],
      "description": "Sector to snapshot. Use all to receive energy, metals, and ags together."
    }
  },
  "required": [
    "sector"
  ],
  "additionalProperties": false
}

calendar.get

List EIA, USDA, and CFTC release calendar entries with cadence, typical Eastern time, and next-hint notes. Free discovery tool — call before scheduling agents around inventory or WASDE prints.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

decision.get

Build a deterministic decision pack for energy, metals, ags, or all sectors. Returns method, signals with direction/rationale, an embedded snapshot, and a disclaimer — no ML model, rule-based only.

Parameters1

sector

string

required

Sector for the decision pack. Use all to bundle every sector.

Raw schema

{
  "type": "object",
  "properties": {
    "sector": {
      "type": "string",
      "enum": [
        "energy",
        "metals",
        "ags",
        "all"
      ],
      "description": "Sector for the decision pack. Use all to bundle every sector."
    }
  },
  "required": [
    "sector"
  ],
  "additionalProperties": false
}

Install

Tools (11)

catalog.listprice.latestinventory.getpositioning.getspread.getprice.historyfx.latestfundamentals.get

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://api.commodities.sh/api/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "commodities-sh": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.commodities.sh/api/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

io.github.sawftware-apps/commodities-sh Model Context Protocol (MCP) Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

catalog.list

price.latest

inventory.get

positioning.get

spread.get

price.history

fx.latest

fundamentals.get

snapshot.get

calendar.get

decision.get

Install

Remote endpoint

Related servers