usda-esmis
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-esmis
Typed Python client, MCP server and FastAPI routes for USDA ESMIS, the Economics, Statistics, and Market Information System of USDA's National Agricultural Library, 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-esmis # client only
uv add "xippios-usda-esmis[mcp]" # + MCP server
uv add "xippios-usda-esmis[http]" # + FastAPI routerNo API key is needed.
Related MCP server: usda-nass
30-second example
from pathlib import Path
from xippios.usda.esmis import download_release_file, get_latest_release, list_release_files
latest = get_latest_release("wasde") # the newest WASDE release
latest.data.id, latest.data.release_datetime # "796099", 2026-10-09 12:00:00+00:00, as printed
latest.meta.vintage # "796099": the release id
latest.meta.published_at # 2026-10-09 12:00:00, the printed time without its +0000
latest.meta.published_at_naive # True: upstream's text, no zone attached (ADR-0022)
files = list_release_files(int(latest.data.id))
[file.format for file in files.data] # ["pdf", "txt", "xls", "xml"]
# Python only, no MCP tool: streams the TXT to the path you name; nothing is cached
txt = download_release_file(796099, "txt", Path("wasde1026.txt"))
txt.data.path, txt.data.bytes, txt.data.content_type # wasde1026.txt, 122378, "text/plain"
txt.meta.endpoint # "wasde1026.txt": the file's name as upstream prints itsearch_publications("wasde") finds a publication's identifiers, and
list_releases("wasde", since=date(2026, 1, 1)) its releases since a date, newest first.
list_recent_releases(since=date(2026, 10, 20)) lists what USDA released across every
publication since a date, latest catalogued first; it needs since or page: every
release of every publication is 61,681 pages, about 34 hours at 30 requests a minute.
A walk from a since before 2025-09-12, ESMIS's migration, is refused, as the older
ids do not follow the release dates; list_releases or page serves older dates.
list_publications() answers from the table of 2522 publications packaged with this
version, fetched on 2026-10-27, without a request:
from xippios.usda.esmis import list_publications
wheat = list_publications(search="wheat") # id, identifier or title contains "wheat": 30
ers = list_publications(agency_acronym="ERS") # as list_agencies() spells it: 121
ers.meta.retrieved_at # 2026-10-27 17:24:48+00:00, when the table was fetched
ers.meta.endpoint # "esmis_api_publication_findAll", the operation it came fromAn acronym the packaged agency table lacks raises UnknownCode, an
InvalidRequestError naming the closest ("ers": did you mean ERS?).
MCP
{
"mcpServers": {
"usda-esmis": {
"command": "uvx",
"args": ["--from", "xippios-usda-esmis[mcp]", "xippios-usda-esmis-mcp"]
}
}
}Tools are read-only and named usda_esmis_<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.
Four tools keep the default with a note naming their own parameters:
usda_esmis_list_publications says how to filter (unfiltered, its packaged table is
about 600 KB, so the tool returns its first 200 rows, while list_publications() in
Python and its HTTP route return the whole table), usda_esmis_list_releases and
usda_esmis_list_recent_releases name since, until and page, and
usda_esmis_search_publications names page.
download_release_file is no tool and no route: a bulk task, Python only (ADR-0019).
--http serves streamable HTTP instead of stdio.
Status
Upstream operation | Task function | MCP tool | Status |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
|
| alpha |
|
| none, Python only | alpha |
Where the live API deviates from its OpenAPI document (probed 2026-10-27)
The OpenAPI document in docs/upstream/openapi/esmis_public_api.yaml is the reference
for names and parameters; the live API answers differently in these points:
every
idis a JSON string, not an integer; the walk of every/publication/findAllpage on 2026-10-27 (pages 0 to 100) found 2522 publications with distinct ids, each a string of digits;Publication.agency,.identifierand.agency_acronymare arrays, not strings;agency_acronymis absent on the publications the four other publication operations answer, which carrypublication_agency_export_1instead;/publication/findAllcarriedagency_acronymon all 2522 publications of the walk andpublication_agency_export_1on none;Publication.frequencyprinted""on one publication of the walk (1172), a value the document's enumeration does not list;status,subscribableandresource_typeheld only the document's values;the list wrapper has
filters,sortersandsystem({"page_key": "page"}) besidepagerandresults;/publication/searchwithoutquery, or with an empty one, answers 200 with"pager": []and empty results, although the document makesqueryrequired;absence answers differ per lookup, as recorded: an unknown id answers 404
{"message": ""}at/agency/findById,/publication/findById,/release/findByIdand/release/findByPubId; an unknown name answers 200 with nothing,/agency/findByAcronyman empty array,/publication/findByAgency,/publication/findByIdentifierand/release/findByIdentifierempty results with every pager count 0;an identifier carrying
/(Market and Trade Economics Division/FDS) cannot be looked up: the web server answers%2Fin a path with its own HTML 404, and a raw slash is no route; every publication recorded with such an identifier has another without it (FDS);pageis 0-based and a page holds 25 items, as the YAML's defaults say; undocumented are that the page size is fixed and that a page past the last answers empty results withcurrent_pageclamped;the orders are undocumented:
/release/findAllcomes highest id first, the newest created, for the releases catalogued since ESMIS's migration, whose first WASDE release is 791996 of 2025-09-12, withrelease_datetimeonly mostly in that order (page 0 of 2026-10-27 runs 2026-10-26, 2026-10-09, 2026-10-23, and page 1 of 2026-10-28 runs 2026-10-09, 2026-09-28, 2026-10-07; 14 days, release 796123 against 796122, is the largest gap on those two pages, whichlist_recent_releasestakes as its walk's tolerance); below the migration the ids do not follow the dates (WASDE's 96165 to 96171 run May, April, March, February, August, July and June 2025, and 95511 of 2022-08-12 and 95621 of 2013-08-12 sit above 95482 of 2025-01-10), solist_recent_releasesrefuses a walk from asincebefore 2025-09-12; a publication's releases (/release/findByIdentifier) come latestrelease_datetimefirst whatever their ids, as recorded on WASDE's pages 0 and 1 (50 releases, 2026-10-09 back to 2022-08-12); publication lists follow no id order (/publication/findAllpage 0: ids 2425, 1801, 1861, 1922;/publication/search?query=wasde: 1762, 1831, 1154);release_datetimeisYYYY-MM-DDTHH:MM:SS+0000(a zone, no colon);Release.filespaths take two shapes: recent releases use/sites/default/release-files/{release id}/{name}.{ext}(/sites/default/release-files/796099/wasde1026.txt), older ones the hashed three-segment path the YAML's example shows (/sites/default/release-files/8336h188j/2514qk05k/j0991c960/prog3925.pdf);Publication.upcoming_releasesis[]on most publications: the walk found items on 24 of 2522, 67 in all, each printed with an Eastern offset (2026-10-28T15:00:00-0400and2026-11-04T15:00:00-0500for publication 1863), whererelease_datetimeprints+0000; the YAML lists no release-calendar operation;the zone label of release times: the API prints
release_datetimewith+0000and the release page itsdatetimewithZ(2026-10-09T12:00:00+0000anddatetime="2026-10-09T12:00:00Z"for the October 2026 WASDE), while the release calendar, whose settings saytimeZone: "America/New_York", puts the WASDE releases that/release/findByIdentifier/wasde(page 0) prints as2025-09-12T12:00:00+0000and2025-12-09T12:00:00+0000at2025-09-12T12:00:00-04:00and2025-12-09T12:00:00-05:00, and the October release's own file answersHEAD /sites/default/release-files/796099/wasde1026.txtwithLast-Modified: Fri, 09 Oct 2026 16:01:00 GMT, 12:01 Eastern. The+0000/Zlabel is contradicted by upstream's own calendar and file timestamps, which fit a noon Eastern wall-clock time (the recorded download ofwasde1026.txtanswers the sameLast-Modified); the tasks keeprelease_datetimeas printed, and those about one release put its wall-clock time, the+0000dropped, intometa.published_atwithpublished_at_naiveset (ADR-0022; CLAUDE.md, release times);the release calendar page (
docs/upstream/pages/release-calendar.md) held 3776 events, drawn from apublication_upcoming_releasesfield (each event'sstartField), while the API'sPublication.upcoming_releaseslists 67 upcoming releases on 24 publications; every calendar event is classedfc-event-past, future ones included, and WASDE's events stop at 2025-12-09.
Upstream terms and attribution
Data comes from USDA ESMIS (https://esmis.nal.usda.gov) under its own terms of use;
this package adds no rights to it. The documentation and the release files are works of
the United States Government (USDA National Agricultural Library, ESMIS), in the public
domain in the United States (17 U.S.C. § 105); a suggested credit line is "Source:
USDA National Agricultural Library, ESMIS". The pages the snapshot reads print no
copyright line, and USDA's policy page is cited in docs/upstream/FETCHED.md,
Attribution. 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
Search and preview datasets publicly. Account-required full data via MCP.
Browse and query the EIA API v2 — electricity, petroleum, natural gas, coal, forecasts via MCP.
Query U.S. Census Bureau data, variables, and geography via MCP.
Read authorized Loam tables and supported external databases through a bounded MCP connection.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables bounded, read-only access to approved HEC-HMS text project files and selected scalar, gage, and control/run relationship fields through MCP tools. Returns compact source-verified answers with versions, units, counts, truncation, and blockers while enforcing configurable root, row, character, and time limits.MIT
- 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 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