xippios-usda-esr-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
xippios-usda-esr
Typed Python client, MCP server and FastAPI routes for USDA FAS Export Sales Reporting, part of the xippios SDK family. Names and semantics follow the upstream documentation; every response carries release metadata (source, endpoint, retrieved_at, published_at, vintage).
Install
uv add xippios-usda-esr # client only
uv add "xippios-usda-esr[mcp]" # + MCP server
uv add "xippios-usda-esr[http]" # + FastAPI routerSet DATA_GOV_API_KEY in the environment. Nothing is read from files.
Related MCP server: usda-nass
30-second example
from xippios.usda.esr import get_exports, get_market_year, get_release_dates
result = get_exports(104, 2024, 1220) # wheat white, market year 2024, to Canada
week = result.data[-1]
week.week_ending_date, week.accumulated_exports, week.unit_id # 2024-06-06, Decimal('16217'), 1
result.meta.vintage # "2024-06-06": the latest week ending date in the answer
result.meta.published_at # None: get_release_dates tells when ESR released the data
result.meta.retrieved_at, result.meta.request
releases = get_release_dates() # one record per commodity
wheat = next(r for r in releases.data if r.commodity_code == 104)
wheat.market_year, wheat.market_year_start, wheat.release_time_stamp # 2027, 2026-06-01, ...
releases.meta.vintage # "2026-10-22T08:30:42.67": store it for the next call
changed = get_release_dates(since=releases.meta.vintage) # released strictly later only
changed.data, changed.meta.vintage # [] when nothing was released since; the newest release
year = get_market_year(104).data # wheat white's current market year, one record
year.market_year, year.market_year_start, year.market_year_end # 2027, 2026-06-01, 2027-05-31Codes are ESR's own integers (commodity 104 wheat white, 401 corn, 801 soybeans;
country 1220 Canada, 2010 Mexico, 5880 Japan), checked against the lists packaged
in reference/ before any call: ESR answers an unknown code with an empty list, so the
package refuses it and names the closest codes. A market year is ESR's, named by the year
it ends in and different per commodity (wheat 2024 is June 2023 to May 2024; corn and
soybeans run September to August, cotton August to July). Leave out the country for every
destination at once, one row per destination and week; the MCP server returns at most
200 rows per call, so pass a country there. Quantities are Decimal in Python and JSON
numbers over MCP and HTTP, in the unit unit_id names (enums.UnitId).
The slices make the requests get_exports makes and only select and order their
records; nothing is excluded, so 9990 UNKNOWN ranks like a country when ESR sends it.
get_weekly_series makes one request per market year from start_year to end_year,
at most 10 market years per call:
from xippios.usda.esr import get_latest_week, get_top_destinations, get_weekly_series
from xippios.usda.esr.models import ExportField
week = get_latest_week(1201, 2024) # cottonseed: the newest week, one row per destination
len(week.data), week.meta.vintage # 11, "2024-08-01"
top = get_top_destinations(1201, 2024, ExportField.OUTSTANDING_SALES, n=3)
[r.country_code for r in top.data] # [5800, 5880, 5230], largest first, ties in upstream order
series = get_weekly_series(104, 1220, 2023, 2024) # wheat white to Canada, two requests
len(series.data), series.meta.vintage # 107 (53 + 54 weeks), "2024-06-06"A week that straddles two market years comes once for each, the older one's row first:
the week ending 2023-06-01 closes wheat's 2023 and opens its 2024. A market year ESR holds
no data for is skipped, so get_weekly_series(104, 1220, 1900, 1900) is an empty list.
ESR answers a market year it has not released with an empty list, as it answers a year
without exports, so a range past the commodity's current market year raises
NotFoundError naming the latest released one (get_market_year names it; wheat: 2027
in October 2026); a range ending in the current calendar year or later reads the release
list first, one request more.
field takes upstream's names of the eight quantities ("outstandingSales",
"accumulatedExports", ...; models.ExportField), which the MCP and HTTP schemas list.
The list_* tasks look codes up in the packaged lists, without a call:
from xippios.usda.esr import list_commodities, list_countries
result = list_countries(region_id=11) # ESR's region WESTERN HEMISPHERE (list_regions)
[c.country_code for c in result.data][:3] # [1010, 1220, 1610], 40 in upstream order
result.meta.endpoint, result.meta.retrieved_at # "ESRData_GetCountries", 2026-10-28T19:19:52Z
list_countries(search="united").data # 4120, 5200, 7830: code, name, description or GENC code
list_countries(search="deu").data # 4280 GERMANY, by its GENC code "DEU"
list_commodities(search="wheat").data # 101 to 107 and 201 Wheat Productsmeta.retrieved_at of a list is when the package fetched it, and its meta.vintage is
None, since upstream gives these lists no version. Names are upstream's, padding
included: country_name is "CANADA ". The list tasks spend no request of the
api.data.gov quota.
MCP
{
"mcpServers": {
"usda-esr": {
"command": "uvx",
"args": ["--from", "xippios-usda-esr[mcp]", "xippios-usda-esr-mcp"],
"env": { "DATA_GOV_API_KEY": "..." }
}
}
}Tools are read-only and named usda_esr_<verb>_<noun>. Results are capped, at
200 rows or 64 KB unless a tool has a cap of its own, with a note on how to see the rest;
usda_esr_list_countries has a cap of its own, 250 rows, so all 211 countries arrive.
usda_esr_get_weekly_series keeps the default, about three market years of one
destination, and its note says to narrow start_year and end_year.
--http serves streamable HTTP instead of stdio.
Status
Upstream operation | Task function | MCP tool | Status |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha; slice |
|
|
| alpha; slice |
|
|
| alpha; slice over a range of market years, one request per market year, at most 10; a range past the commodity's current market year is refused |
|
|
| alpha; |
|
|
| alpha; one commodity's record |
|
|
| packaged; |
|
|
| packaged; |
|
|
| packaged; |
|
|
| packaged, |
0.1.0, the first release, covered nine of these tasks; 0.2.0 adds get_market_year,
since on get_release_dates and the range of get_weekly_series, which replaces its
0.1.0 market_year. Alpha: the public surface may change in a minor version before 1.0
(conventions §12); CHANGELOG.md lists every change.
Every request counts against api.data.gov's quota of 1,000 requests per hour per key,
shared by every package using the same DATA_GOV_API_KEY; the list_* tasks spend none.
The client keeps its own pace of one request per second; once the quota is spent it waits
for the quota to come back when that takes at most 30 s, and otherwise raises
RateLimitError with retry_after instead of sending.
Upstream terms and attribution
Data comes from USDA FAS Export Sales Reporting (https://www.fas.usda.gov/programs/export-sales-reporting-program) under its own terms of use;
this package adds no rights to it. Documentation snapshot: docs/upstream/.
Licence
Apache-2.0. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
UN Comtrade international trade statistics via MCP. Country/HS lookups, flows, balances, rankings.
Primary-source commodities for agents — EIA, USDA, CFTC, IMF, USGS, FAOSTAT, Comtrade. 30 tools.
Read-only, source-linked cattle, sheep, and goat prices, market reports, coverage, and methodology.
Read-only cited financial datasets, bounded research queries and source diagnostics.
Related MCP Servers
AlicenseNot gradedqualityBmaintenanceEnables access to USDA Foreign Agricultural Service trade and global production data through MCP, supporting natural language queries and tool-based data retrieval.173 npmMIT- AlicenseNot gradedqualityBmaintenanceExposes read-only tools for querying USDA NASS Quick Stats, covering reported counts, filtered data pulls, parameter values, crop progress and condition, county yield and production, acreage and forecasts, and prices received. Results are capped with guidance on narrowing queries.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceExposes read-only tools for querying USDA FAS PSD Online commodity supply and distribution data, with every response carrying release metadata such as source, endpoint, retrieval time and vintage. Results are capped by row count and size, with guidance returned on how to narrow a query.45 PyPIApache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables searching USDA AMS Livestock Mandatory Price Reporting market news reports and reading dated price rows — direct slaughter cattle, boxed beef and pork cutouts, hogs and lamb — keeping low, high and weighted-average prices separate with each report's own basis fields. It also reports clearly when a requested date, section or commodity family has no AMS coverage instead of returning empty results.289 npmMIT