Skip to main content
Glama
ameriflux-mcp

ameriflux-mcp

by idss-mesa

ameriflux-mcp

MCP 2026-07-28 License: MIT Docs

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 identity

scripts/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-mcp

Clients 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

amf_ping

Server version, protocol and configuration status

amf_search_sites

Find AmeriFlux, FLUXNET2015 and FLUXNET-CH4 sites by place, ecosystem, years, product and policy

amf_get_site

One site's metadata, DOIs, products and links to NEON/EDI

amf_get_availability

Which years each product has per site, and under which policy

amf_search_variables

Search the FP Standard and FLUXNET variable dictionaries

amf_describe_variables

Parse variable names (qualifiers, QC, units per resolution, heights)

amf_get_citation

Versioned citations, required acknowledgments and policy obligations

amf_get_badm

Site metadata (BADM): location, team, disturbance, funding, references, instruments and heights

amf_download_data

Opt-in, consented download through AmeriFlux's logged route (stdio only)

amf_list_files

Classify downloaded zips and CSVs

amf_preview_data

Summaries and row windows from local files, with QC filtering

amf_read_bif

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 tools
amf_describe_variablesDescribe variable names: grammar, units, QC and sitesA
Read-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 productA
Read-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 metadataA
Read-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 sitesA
Read-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 siteA
Read-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 filesA
Read-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 statusA
Read-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 fileA
Read-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) fileA
Read-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 sitesA
Read-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 dictionariesA
Read-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

    A4/5.0

    Scored across 11 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      20
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      MIT