ameriflux-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ameriflux-mcp Find AmeriFlux sites in California with 2020 data and show citation rules."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ameriflux-mcp
A Model Context Protocol server (spec 2026-07-28) for AmeriFlux and FLUXNET eddy-covariance data. It lets agents find flux tower sites, check which products and years exist, understand FLUXNET variable names and QC flags, cite data under the right data policy, download with the user's consent, and preview files: AmeriFlux BASE and BADM, the AmeriFlux FLUXNET (FLUXNET-1F) product, and FLUXNET2015 FULLSET and SUBSET.
Status: v0.1.0. Twelve tools (eight over HTTP), three prompts and the guide and reference resources described below. The AmeriFlux API is undocumented, so the server checks every response's shape and reports drift instead of guessing. See DESIGN.md for decisions, RESEARCH.md for verified API facts, and CHANGELOG.md for what changed.
Installation
Full instructions for macOS, Linux and Windows are in the documentation: docs/getting-started/install.md (published at https://idss-mesa.github.io/ameriflux-mcp/ once the repository is public).
Prerequisites: uv, git, and read access to this private
repository (for example through gh auth login).
git clone https://github.com/idss-mesa/ameriflux-mcp.git
cd ameriflux-mcp
scripts/install.sh # registers the server with every agent it finds
scripts/install.sh --with-identity # ... and stores your AmeriFlux download identityscripts/install.sh creates the environment with uv sync, checks that
ameriflux-mcp --version runs (it never registers a command that does not start), and
registers the server with Claude Code, Claude
Desktop, OpenAI Codex CLI, Gemini CLI, Goose and OpenCode. On Windows run it from Git
Bash. --dry-run previews every change; --uninstall removes them.
Manual registration, for Claude Code:
claude mcp add ameriflux -s user -- /absolute/path/to/ameriflux-mcp/.venv/bin/ameriflux-mcpClients has the entries for every other client.
Once v0.1.0 is on PyPI: uvx ameriflux-mcp (or uv tool install ameriflux-mcp). A
Dockerfile serves the read-only HTTP tools: docker compose up -d, then
http://127.0.0.1:8080/mcp.
Related MCP server: io.github.krnzt/ecoscope
Tools
Tool | What it does |
| Server version, protocol and configuration status |
| Find AmeriFlux, FLUXNET2015 and FLUXNET-CH4 sites by place, ecosystem, years, product and policy |
| One site's metadata, DOIs, products and links to NEON/EDI |
| Which years each product has per site, and under which policy |
| Search the FP Standard and FLUXNET variable dictionaries |
| Parse variable names (qualifiers, QC, units per resolution, heights) |
| Versioned citations, required acknowledgments and policy obligations |
| Site metadata (BADM): location, team, disturbance, funding, references, instruments and heights |
| Opt-in, consented download through AmeriFlux's logged route (stdio only) |
| Classify downloaded zips and CSVs |
| Summaries and row windows from local files, with QC filtering |
| Read BADM Interchange Format files |
The last four run only over stdio, on the user's machine. Prompts: find_flux_sites,
plan_site_analysis, cite_flux_data. Guides for agents: ameriflux://guide/agent-workflow,
products, data-policy, variable-grammar, identity, file-formats,
fluxnet2015-access.
Downloads disclose who you are
AmeriFlux downloads go through a request that sends your name, email and stated purpose
to the site's principal investigators and to the AmeriFlux download log. ameriflux-mcp
never invents that information or lets a model write it: it comes only from your own
configuration, every download shows you the exact text first, and nothing is sent until
you confirm. Downloads are off by default until AmeriFlux confirms third-party use
of its download request; AMERIFLUX_MCP_DOWNLOADS__ENABLED=true (or --downloads)
turns them on. Discovery, availability, variables and citations need no identity at all.
Data policy
AmeriFlux data are shared under the CC-BY-4.0 licence or the AmeriFlux Legacy policy; FLUXNET2015 under CC-BY-4.0 (Tier 1) or Tier 2. Cite each site's DOI and include the required acknowledgments: see the AmeriFlux data policy and the FLUXNET data policy.
License
MIT, Copyright (c) 2026 The Regents of the University of New Mexico. Third-party credits are in NOTICE.
Available Tools
11 toolsamf_describe_variablesDescribe variable names: grammar, units, QC and sitesARead-onlyIdempotent
Decode up to 20 variable names from BASE or FLUXNET files: base name and FP Standard definition with QA/QC range, qualifiers (_PI, _QC, _F, _IU), position (_H_V_R, _H_V_A, _#), FLUXNET processing tokens (MDS, VUT/CUT, NT/DT, REF, percentiles), units and QC meaning per resolution, sign conventions. With site: whether the site measures it, sensor heights and instruments, yearly coverage. Next: call amf_get_availability for the site's years.
Inputs: names (required), site, resolution. Returns: page, notes, source, resolved, +2 more
amf_get_availabilityGet data availability per site and productARead-onlyIdempotent
Published years per site for AmeriFlux BASE-BADM and FLUXNET (FLUXNET-1F), FLUXNET2015 and FLUXNET-CH4, and BADM (BIF) membership, each labelled with the data policy it is shared under (CC-BY-4.0, Legacy, Tier Two). Lists requested sites without data and why, and the policy the selection must follow with its obligations. Invalid product/policy pairs fail before any request. Next: call amf_get_citation for these sites.
Inputs: limit, sites, years, offset, +2 more. Returns: page, rows, notes, source, +6 more
amf_get_badmGet a site's BADM metadataARead-onlyIdempotent
A site's Biological, Ancillary, Disturbance and Metadata as the API exposes it, by group: location, IGBP and climate, tower dates, team (no emails by default), disturbance and management, funding sponsors and organizations (needed to acknowledge Legacy sites), reference papers, and instruments with measurement heights. The full BADM ships as the BIF file in BASE-BADM downloads. Next: call amf_get_citation to cite the site.
Inputs: site (required), include, variables, include_contacts, +2 more. Returns: name, site, team, notes, +10 more
amf_get_citationGet citations and acknowledgments for sitesARead-onlyIdempotent
Citations for up to 50 sites and one product (BASE-BADM, BIF, FLUXNET, FLUXNET2015): AmeriFlux's own versioned text per site DOI (e.g. 'Ver. 28-5'), the policy the selection must follow with its obligations (mixing CC-BY and Legacy means Legacy; mixing tiers means Tier Two), verbatim acknowledgments, Legacy site funding, the data-availability sentence and processing papers. Optional BibTeX. Next: cite every site in the reference list and follow the obligations.
Inputs: sites (required), product, include_bibtex. Returns: page, notes, source, missing, +10 more
amf_get_siteGet one AmeriFlux or FLUXNET siteARead-onlyIdempotent
One site by ID (any case), NEON code, FLUXNET2015 old ID or name: location, IGBP and Köppen with AmeriFlux's descriptions, data policy and what it means, DOIs, years per product (BASE, FLUXNET, FLUXNET2015, FLUXNET-CH4), member networks, links to NEON and to LTER data in EDI, team (no emails by default), measured BASE variables. Next: call amf_get_availability for exact years or amf_get_citation to cite it.
Inputs: site (required), include, include_contacts. Returns: dois, name, team, notes, +19 more
amf_list_filesList local AmeriFlux and FLUXNET filesARead-onlyIdempotent
Find the AmeriFlux and FLUXNET files already on this computer, in the download directory and configured local roots: BASE and BASE-BADM zips, BIF files, AmeriFlux FLUXNET (ONEFlux) and FLUXNET2015 archives, with each archive's members classified by kind (data, ERA, BIFVARINFO, BIF, aux tables), site, resolution, years and version. Unsafe members are flagged. stdio only. Next: call amf_preview_data(file=...) on one.
Inputs: path, site, limit, family, +2 more. Returns: page, files, notes, roots, +6 more
amf_pingCheck ameriflux-mcp statusARead-onlyIdempotent
Liveness and capability report: server version, protocol and transport; whether a download identity is configured (booleans and profile names only, never the values) and which tools need it; whether downloads are enabled and where files go. With check_api=true it also makes one small request to the AmeriFlux API to confirm connectivity. Next: read ameriflux://guide/identity to set up downloads.
Inputs: check_api. Returns: pong, cache, notes, source, +12 more
amf_preview_dataPreview a local AmeriFlux or FLUXNET data fileARead-onlyIdempotent
Summarize or page through a local BASE, AmeriFlux FLUXNET or FLUXNET2015 CSV, in place or inside its zip: time step and range, per-column count, missing (-9999), min, max, mean and out-of-range counts, units per resolution, a time window, a QC filter, UTC timestamps from the site's BIF, a SUBSET column view, and aux tables. Stops within a byte and time budget. stdio only. Next: call amf_describe_variables on columns to decode.
Inputs: end, file, mode, site, +10 more. Returns: page, rows, scan, notes, +6 more
amf_read_bifRead a local BADM (BIF) fileARead-onlyIdempotent
Read a local BADM Interchange Format file, the site metadata shipped in BASE-BADM (xlsx) and AmeriFlux FLUXNET (CSV) downloads, also from inside the zip: entries by group (location, IGBP, team, instruments, disturbance …), UTC offsets with their start dates, the DOI and citation recorded for that version, and funding acknowledgments. Emails and addresses are withheld by default. stdio only. Next: call amf_get_citation for the current citation.
Inputs: file, site, limit, groups, +3 more. Returns: page, notes, source, entries, +7 more
amf_search_sitesSearch AmeriFlux and FLUXNET sitesARead-onlyIdempotent
Find flux tower sites in the AmeriFlux (856), FLUXNET2015 (212) and FLUXNET-CH4 (81) catalogs by words, place (bbox or near a point), IGBP ecosystem, Köppen climate, country/state, status, member network (NEON, LTER, ...), data product and policy, years with data, measured variables or gas species. Returns compact site summaries with years per product, facets over all matches, and paging. Next: call amf_get_site for one site or amf_get_availability for exact years.
Inputs: gas, bbox, igbp, near, +15 more. Returns: page, notes, sites, facets, +3 more
amf_search_variablesSearch the FP Standard and FLUXNET variable dictionariesARead-onlyIdempotent
Find variable names in the FP Standard list (AmeriFlux BASE, live, with QA/QC ranges) and the FLUXNET dictionaries (AmeriFlux FLUXNET from ONEFlux v1.3; FLUXNET2015 FULLSET and SUBSET), by words, category or resolution. FLUXNET units change with resolution (NEE is umol m-2 s-1 at HH, gC m-2 d-1 at DD), so each result lists units per resolution and SUBSET membership. Next: call amf_describe_variables on the names.
Inputs: limit, query, offset, category, +2 more. Returns: page, notes, facets, source, +3 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools occupy clearly separate niches: search_* returns candidate lists, get_* pulls one entity, and the local-file tools (list_files, preview_data, read_bif) are distinct from the API tools. A few pairs are close — describe_variables vs. search_variables (both about variable names) and get_badm vs. read_bif (BADM metadata via API vs. from a local file) — but the descriptions explicitly anchor them to different sources and workflows.
Every tool carries the amf_ prefix and follows a clean snake_case verb_noun pattern (get_site, search_sites, describe_variables, read_bif, list_files), with only the conventional bare 'ping' deviating. The naming is fully predictable and reinforces the search/get/describe groupings.
Eleven tools is a well-scoped set for a site-catalog + metadata + local-file-inspection server, and each tool maps to a concrete step in the discovery-to-analysis workflow. No filler or redundant wrappers are present.
The discovery, metadata, citation and local-file reading surface is rich, but the download step appears absent from the tool list even though amf_ping describes configured download identities, enabled downloads, and 'which tools need it' — leaving a gap between finding a site and reading its data. There is also no write/export or bulk-extraction operation, so agents may hit a dead end after previewing files.
Maintenance
Related MCP Connectors
Use your Fulcra secure context lake to collaborate with other agents, read and write data, and more
Search DataCite datasets and software, fetch DOI metadata, trace relations, format citations.
Real-world data for agents: air quality, geocoding, quakes, holidays, web search
Search, read and cite documents. Add, replace and delete files with write access. OAuth required.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables querying and exporting phenology data from the USA National Phenology Network, including raw data, phenometrics, and mapping capabilities.103MIT
- AlicenseNot gradedqualityDmaintenanceEnables MCP agents to discover, import, query, visualize, select, and cite NEON and local scientific datasets while keeping credentials, private paths, and bulk data out of model context.MIT
- AlicenseAqualityBmaintenanceEnables AI agents to discover NEON ecological data products and sites, check data availability, list and download data files, and generate citations via the NEON Data API.20MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to search Earth-science dataset collections by keyword, platform, instrument, time range, or bounding box; fetch full collection metadata; and list individual data granules with direct download links.81 npmMIT