usda-psd
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-psd
Typed Python client, MCP server and FastAPI routes for USDA FAS PSD Online, 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-psd # client only
uv add "xippios-usda-psd[mcp]" # + MCP server
uv add "xippios-usda-psd[http]" # + FastAPI routerSet DATA_GOV_API_KEY in the environment. Nothing is read from files.
Related MCP server: usda-gats
30-second example
from xippios.usda.psd import get_data
from xippios.usda.psd.enums import AttributeId
result = get_data("0410000", 2023, "US") # wheat, market year 2023, United States
production = next(r for r in result.data if r.attribute_id == AttributeId.PRODUCTION)
production.value, production.unit_id # Decimal('49095.0'), 8 (UnitId._1000_MT)
result.meta.vintage # "2026-07": the PSD release that last revised these figures
result.meta.published_at # None: PSD gives a month, no day
result.meta.retrieved_at, result.meta.requestCodes are PSD's own (commodity 0410000 wheat, 0440000 corn, 2222000 soybeans;
country US, BR, E4), checked against the lists packaged in reference/ before any
call. Leave out the country for every country at once, or use get_world_data for the
world total. attribute_id and unit_id are PSD's integer ids; enums.AttributeId and
enums.UnitId name the packaged ones and compare equal to them. The MCP server returns
at most 200 rows per call, and every country at once is up to about 1,900 rows, so pass a
country there. get_release_dates tells when PSD last revised each country and market
year; compare it with a stored meta.vintage, or pass that vintage as since, to fetch
only what changed.
The list_* tasks look codes up in the packaged lists, without a call:
from xippios.usda.psd import list_commodities, list_countries
result = list_countries(region_code="R01") # PSD's region North America (list_regions)
[c.country_code for c in result.data] # ["CA", "GL", "MX", "SB", "US"], upstream order
result.meta.endpoint, result.meta.retrieved_at # "PSDData_GetCountries", 2026-10-28T21:42:03Z
list_countries(search="united").data # TC, UK, US: code, name or GENC code, ignoring case
list_countries(search="usa").data # US United States, by its GENC code "USA"
list_commodities(search="soybean").data # meal, oil and oilseed, each also "(Local)"meta.retrieved_at of a list is when the package fetched it, and its meta.vintage is
None, since upstream gives these lists no version. Over MCP usda_psd_list_countries
returns all 251 countries through a cap of its own.
The slices answer the common questions from the same operations. They select, order or pivot upstream's records and change none: no derived totals, no unit conversion, no gap filling.
from xippios.usda.psd import (
get_balance_sheet,
get_latest_release,
get_time_series,
get_top_countries,
)
from xippios.usda.psd.enums import AttributeId
sheet = get_balance_sheet("0410000", "US", 2023).data # wheat, United States, one request
list(sheet.attributes) # ["Area Harvested", "Beginning Stocks", "Production", ...], 15
sheet.attributes["Production"] # attribute_id=28, unit_id=8 (1000 MT), value=Decimal("49095.0")
series = get_time_series("0440000", "US", 2021, 2023, attribute_id=AttributeId.PRODUCTION)
[(r.market_year, r.value) for r in series.data] # 3 requests; one record per year with data
get_time_series("0440000", "US", 2023, 2023, attribute_id=[28, 88]) # production and exports
get_time_series("0440000", "US", 2023, 2023) # every attribute of 2023
top = get_top_countries("2222000", 2023, AttributeId.PRODUCTION, n=5) # soybeans, one request
[r.country_code for r in top.data] # largest first; "E4" (EU) and aggregates rank too
get_top_countries("2222000", 2023, 28, n=5, region_code="R04", exclude_groupings=True)
latest = get_latest_release("0410000") # the countries and market years of the newest release
latest.meta.vintage # "2026-10", comparable with get_data's meta.vintage
get_latest_release("0410000", since=latest.meta.vintage).data # [] until a newer releaseget_balance_sheet keys each entry by the attribute's upstream name; an id whose name
upstream gives to several ids ("Total Disappearance" is 126 and 173) always carries the
id, "Total Disappearance (126)", and each entry keeps its own unit_id.
get_time_series starts at 1960 at the earliest, spans at most 100 market years per
call, spends one request per market year,
leaves a year without data out, and counts against the hourly quota like every other
request; without attribute_id it keeps every attribute.
get_top_countries ranks PSD's groupings (E4 European Union, T3 Africa, NEC, ...)
alongside countries unless exclude_groupings=True, and region_code ranks one PSD
region. get_latest_release(..., since=...) answers an empty list while nothing newer
than since was released, meta.vintage still naming the newest release.
MCP
{
"mcpServers": {
"usda-psd": {
"command": "uvx",
"args": ["--from", "xippios-usda-psd[mcp]", "xippios-usda-psd-mcp"],
"env": { "DATA_GOV_API_KEY": "..." }
}
}
}Tools are read-only and named usda_psd_<verb>_<noun>. Results are capped at
200 rows or 64 KB with a note on how to narrow the query; usda_psd_list_countries has a
cap of its own, 300 rows, so all 251 countries arrive. --http serves streamable HTTP
instead of stdio.
Status
Upstream operation | Task function | MCP tool | Status |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| packaged; |
|
|
| packaged; |
|
|
| packaged; |
|
|
| packaged; |
|
|
| packaged; |
The slices: task-shaped functions over the operations above, no new endpoint.
Upstream operation | Task function | MCP tool | Example | Status |
|
|
|
| alpha |
|
|
|
| alpha |
|
|
|
| alpha |
|
|
|
| alpha |
0.3.0 covers the same twelve tasks as 0.2.0, four of them with new or changed parameters
(get_time_series, get_top_countries, get_release_dates, get_latest_release), and
requires xippios-core 0.3.x (~=0.3.0); 0.2.0 does not work with core 0.3.0. Alpha until
1.0: the public surface may change in a minor version (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 PSD Online (https://apps.fas.usda.gov/psdonline/) 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
AI-powered commodity price forecasts and Brazil trade intelligence via MCP. Access Brazilian exports and imports from MDIC/ComexStat since 2000, by HS4, HS6 and NCM code, partner country, USD FOB and kilograms — plus crop production, supply & demand, climate data and production forecasts for major commodities including soybeans, coffee, corn, beef and cocoa. Compare trade flows, markets, countries and time periods with like-for-like windows. Every answer identifies the measurement period and data source. 15 read-only tools. Metered in credits. Connect directly via Streamable HTTP — no installation required: https://mcp.kyrodata.com/mcp Authentication: Bearer key or OAuth 2.1 (PKCE). Official MCP registry: com.kyrodata/kyrodata
Search 77k public-sector open data APIs across 10 countries. Read-only, no API key.
Read-only discovery for Malaysian public datasets with freshness, licence, and provenance.
UN Comtrade international trade statistics via MCP. Country/HS lookups, flows, balances, rankings.
Related MCP Servers
- 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 gradedqualityBmaintenanceRead-only MCP tools for querying USDA FAS Global Agricultural Trade System census export and import records by partner country, year, month and HS10 code prefix, plus the release-date lists for each flow. Results are capped with notes on omitted rows, and responses carry release vintages and retrieval metadata.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables querying USDA FAS Export Sales Reporting data through read-only tools, including weekly export quantities by commodity, destination country and market year, latest-week and top-destination slices, data release dates, and lookups of commodity, country, region and unit codes. Cross-references ESR's own integer codes against packaged reference lists so valid commodities and destinations are resolved before any request.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables read-only access to USDA ESMIS data through MCP tools, returning capped results with release metadata and guidance for viewing the remainder.Apache 2.0