Download identity¶

Most of ameriflux-mcp needs no account at all: finding sites, checking which years exist, describing variables, getting citations and previewing files you already have all work anonymously. Only downloading data from AmeriFlux needs an identity, and this page explains why, what is disclosed, and how to configure it.

What a download discloses, and to whom¶

AmeriFlux has no API keys. Every download is a request that carries your AmeriFlux user ID, your email, an intended-use category and a short description of how you will use the data. AmeriFlux sends that information to the principal investigators (PIs) of each site you download, and posts it to the AmeriFlux Data Download Log (visible to logged-in users)¹. This is how tower teams learn who uses their data and offer collaboration, so the text should be accurate and written by you.

ameriflux-mcp therefore follows four rules:

1. Your words, not the model's. The identity, intended use and description come only from configuration you wrote. They are never tool arguments, so an AI agent cannot invent or edit them. The server appends [ameriflux-mcp] to the description so AmeriFlux can see which client sent the request.
2. See it first. A download request first returns a plan: the exact text that will be sent, the sites it goes to, and the data policy that applies. Nothing is sent.
3. Then confirm. Only a second call with confirm=true, naming the data policy you accept, sends the request.
4. Only on your machine. The download tool exists only over stdio, on the computer where your agent runs. A hosted (HTTP) ameriflux-mcp never accepts an identity.

ameriflux-mcp never builds download links itself and never uses unofficial mirrors: every file comes through AmeriFlux's logged route, so PIs are notified as they are for downloads from the AmeriFlux website. The links AmeriFlux returns end in a ?=<user ID> tag; ameriflux-mcp strips it before fetching, so only the logged request carries your identity, and nothing it writes to disk (files, checksum sidecars, manifests) contains your user ID, email, name or description.

Create an AmeriFlux account¶

AmeriFlux and FLUXNET share one account system. Create an account on the FLUX User Account Creation page²: full name, institution, email, and a username. The username is your AmeriFlux user ID. The same page links to username lookup and password reset.

A registered account matters most for data under the AmeriFlux Legacy policy: the AmeriFlux website offers Legacy data only to logged-in users. Whether AmeriFlux's API checks the user ID against registered accounts has not been confirmed yet⁴ (question Q2 in the project's support questions).

The settings¶

Each also has a namespaced form (AMERIFLUX_MCP_IDENTITY__USER_ID, …) that wins when both are set, for giving ameriflux-mcp a different identity from other AmeriFlux tools that read the plain names. Look-alike names such as AMERIFLUX_EMAIL, AMERIFLUX_USERNAME, AMF_USER_ID, AMERIFLUX_TOKEN or AMERIFLUX_API_KEY are not read; the server warns if one is set.

Intended use. The six categories AmeriFlux's download form offers:

Profiles. One description rarely fits every project. A YAML configuration file can define named profiles, each with its own intended use and description, and a download picks one with profile="…"; the environment variables above define the default profile:

# ameriflux-mcp.yaml — pass with: ameriflux-mcp --config ameriflux-mcp.yaml
identity:
  profiles:
    default:
      intended_use: other_research
      description: "Comparing drought responses of semi-arid grassland GPP across New Mexico towers."
    teaching:
      intended_use: education
      description: "Classroom exercises on energy-balance closure for an ecosystem ecology course."

Keep the user ID and email in the environment rather than in a file you might share.

is_test¶

AmeriFlux's download request has an is_test flag. The AmeriFlux website sends false for real downloads; other clients behave differently, and exactly what AmeriFlux does with test requests (whether they are logged or sent to PIs) is not documented yet. ameriflux-mcp therefore gives it no default: until you set AMERIFLUX_MCP_IDENTITY__IS_TEST to true (trying things out) or false (real downloads for your work), the download tool refuses with auth_required and reason: is_test_unset.

Give it to ameriflux-mcp¶

scripts/install.sh --with-identity --env AMERIFLUX_MCP_DOWNLOADS__ENABLED=true

claude mcp add ameriflux -s user \
  -e AMERIFLUX_USER_ID=your-username \
  -e AMERIFLUX_USER_EMAIL=you@example.edu \
  -e AMERIFLUX_INTENDED_USE=4 \
  -e AMERIFLUX_DESCRIPTION="Comparing drought responses of semi-arid grassland GPP." \
  -e AMERIFLUX_MCP_IDENTITY__IS_TEST=false \
  -e AMERIFLUX_MCP_DOWNLOADS__ENABLED=true \
  -- ameriflux-mcp

{
  "mcpServers": {
    "ameriflux": {
      "command": "/ABSOLUTE/PATH/TO/ameriflux-mcp",
      "args": [],
      "env": {
        "AMERIFLUX_USER_ID": "your-username",
        "AMERIFLUX_USER_EMAIL": "you@example.edu",
        "AMERIFLUX_INTENDED_USE": "4",
        "AMERIFLUX_DESCRIPTION": "Comparing drought responses of semi-arid grassland GPP.",
        "AMERIFLUX_MCP_IDENTITY__IS_TEST": "false",
        "AMERIFLUX_MCP_DOWNLOADS__ENABLED": "true"
      }
    }
  }
}

Check it with ameriflux-mcp --check or by asking your agent to call amf_ping: the result says which fields are configured, as booleans and profile names, never the values.

Data policy at download time¶

Every AmeriFlux site shares its data under the CC-BY-4.0 license or the more restrictive AmeriFlux Legacy policy, and combining the two means following Legacy for everything¹. FLUXNET2015 uses Tier 1 (CC-BY-4.0) and Tier 2³. The download plan states the policy that applies to the sites you chose, and confirm=true must name it (accept_data_policy="CCBY4.0" or "LEGACY"), so you accept the right terms. The AmeriFlux FLUXNET product exists only for CC-BY sites. Citing AmeriFlux and FLUXNET data lists what each policy asks of you.

FLUXNET2015¶

FLUXNET2015 files are downloaded through a login-protected form on fluxnet.org that also asks for an intended-use statement. ameriflux-mcp does not automate that form. Download the zips yourself, put them in your download directory or a folder listed in local.roots (Configuration), and the local file tools read them.

Privacy¶

Your identity values are masked in logs, --print-config output and the installer's output, and never written to caches, download records or test fixtures. ameriflux-mcp also strips the contact emails of tower teams and DOI contributors from its results unless you explicitly ask for contacts and the operator enabled privacy.allow_contact_emails (off by default), for example to contact PIs as the Legacy policy asks.