Quickstart¶

This walks through a first session in Claude Code¹; other clients work the same way once connected (Clients).

1. Register the server¶

claude mcp add ameriflux -s user -- ameriflux-mcp --transport stdio

No account is needed for this walkthrough. Downloads (step 6 below) need a download identity.

2. Check it¶

Ask the agent to "call amf_ping with check_api=true". The result shows the version, protocol 2026-07-28, the transport, which download-identity fields are configured (as booleans), whether downloads are enabled, and under upstream whether one small request to the AmeriFlux API succeeded.

3. Find towers¶

{"tool": "amf_search_sites", "arguments": {"igbp": ["DBF"], "state": ["MA"], "product": "FLUXNET", "min_years": 10}}

→ deciduous broadleaf forest sites in Massachusetts with at least ten years of AmeriFlux FLUXNET data, each with siteId (such as US-Ha1, Harvard Forest), name, location, IGBP class, data policy and the years per product. Sites also resolve by name or NEON code: amf_get_site(site="SRER") finds US-xSR, the NEON Santa Rita tower, and points to the matching NEON data product.

4. Check what data exist¶

{"tool": "amf_get_availability", "arguments": {"sites": ["US-Ha1", "CA-Let"], "products": ["BASE-BADM", "FLUXNET"]}}

→ the published years per site and product². CA-Let shares its data under the Legacy policy, so it has BASE years but appears in emptySites for FLUXNET, with a note that the FLUXNET product exists only for CC-BY sites.

5. Understand the variables¶

{"tool": "amf_describe_variables", "arguments": {"names": ["GPP_NT_VUT_REF", "TA_F_MDS_QC"], "resolution": "DD"}}

→ GPP_NT_VUT_REF is gross primary production from nighttime partitioning with a variable USTAR threshold, reference realization, in gC m-2 d-1 at daily resolution; TA_F_MDS_QC is the fraction (0–1) of measured or good-quality gap-filled air temperature in each day.

6. Plan a download¶

{"tool": "amf_download_data", "arguments": {"sites": ["US-Ha1"], "product": "FLUXNET"}}

→ a plan, not a download: the exact user ID (masked), email (masked), intended use and description that would be sent to the US-Ha1 PIs, the data policy (CCBY4.0) and what it asks of you. Only confirm=true with accept_data_policy="CCBY4.0" sends the request; the files land in ~/ameriflux-downloads/FLUXNET/ with a checksum record (see Downloads). Then amf_preview_data(site="US-Ha1", product="FLUXNET", resolution="DD") summarizes the daily file without loading it all.

7. Cite it¶

{"tool": "amf_get_citation", "arguments": {"sites": ["US-Ha1"], "product": "FLUXNET"}}

→ the versioned citation AmeriFlux recommends ("… AmeriFlux FLUXNET-1F US-Ha1 Harvard Forest EMS Tower (HFR1), Ver. v1.3_r1 (1991-2025), AmeriFlux AMP, (Dataset). https://doi.org/10.17190/AMF/1871137"), the required acknowledgments, the processing reference and a data-availability sentence. See Citing AmeriFlux and FLUXNET data.

Every result also carries notes (caveats) and nextSteps (concrete follow-up calls), so agents normally chain these on their own.