Availability and data files¶

Three tools take you from "does data exist?" to files on disk: neon_get_availability (no token), neon_list_files (token) and neon_download_files (token for data files; stdio only).

Availability (no token)¶

{"product": "DP1.10003.001", "domain_code": "D01"}

• Product mode (product only): one row per site. Site mode (site only): one row per product. Cell mode (both): one row, months listed explicitly by default.
• Months are compressed to ISO-8601 intervals: ["2016-06/2025-06"]; format can be ranges (default), months or counts.
• byRelease splits every row by release, with PROVISIONAL as its own key, and summary totals site-months per release.
• start_month / end_month window the result. NEON's GraphQL filter windows availableMonths but not the per-release lists, so neon-mcp clips those locally (a note says so).
• Filters: site_codes or domain_code (product mode), product_codes (site mode), release, and provisional = include (default), exclude or only.

PROVISIONAL is not a release¶

Newer data are provisional: available but not yet in an annual release, and they may change. release="PROVISIONAL" is rejected (NEON rejects it too); use the provisional switch here and include_provisional when listing or downloading files. Defaults include provisional data everywhere, so what availability shows is what listing returns.

Listing files (token)¶

Since June 2026 NEON's data endpoints require an API token³; without one the tool fails with auth_required before any request (set one up).

{"product": "DP1.10003.001", "site_codes": ["HARV"], "start_month": "2023-06", "kind": "data"}

• One site and one month uses GET /data/{product}/{site}/{month} (which also returns package ZIP links); anything wider uses POST /data/query².
• Each file carries its name, kind (data, variables, readme, sensor_positions, eml, science_review_flags, categorical_codes, validation, package, other), table, hor/ver/tmi indices, size, MD5, release and a signed URL. Filter with kind, table, hor, ver, tmi, name_contains (see neon://guide/product-code-anatomy for the file-name grammar).
• Signed URLs expire about 7 days after generation (urlExpiresAt); they need no token. List again to refresh them, and never cite them.
• detail="summary" or "site_months" sizes a request without listing files; include_urls=false shrinks the result. Under the 50 KB result budget, URLs are dropped from the end of the page before files are.
• A request may span at most 500 site-months (30 sites × 16 months, for example); wider requests fail with query_too_large before calling NEON.
• filename returns the signed URL of one exact file for a single site-month.

Downloading (stdio)¶

neon_download_files takes the same selectors, or prototype_uuid (+ file_names), or spec_number for a NEON document. It exists only on stdio: the files land on the machine running the server, under downloads.directory (~/neon-downloads):

~/neon-downloads/DP1.10003.001/HARV/2023-06/NEON.D01.HARV.DP1.10003.001.brd_countdata.2023-06.basic.….csv
~/neon-downloads/prototype/<uuid>/<file>
~/neon-downloads/documents/NEON.DOC.014041vL.pdf

Safety rules: the whole plan is checked against 50 files and 2 GiB per call (1 GiB per file) before anything transfers; every destination must resolve inside the download directory (no .., no symlink escapes, plain file names); every URL and redirect must be on the host allow-list (data.neonscience.org, storage.googleapis.com and its subdomains); files stream to .part and are renamed only after the MD5 matches. Existing identical files are skipped (if_exists="error" refuses instead); as_zip=true fetches NEON's package ZIP per site-month.