Configuration¶

ameriflux-mcp runs with no configuration at all: the defaults serve stdio, cache AmeriFlux API responses, keep tool results small, strip contact emails and confine downloads to ~/ameriflux-downloads. Settings come from four layers; a higher layer wins:

1. Command-line flags (only a handful of common settings).
2. Environment variables named AMERIFLUX_MCP_<SECTION>__<FIELD>, with a double underscore descending into nested sections at any depth, for example AMERIFLUX_MCP_CACHE__TTL_S__CATALOG=3600. List settings take a comma-separated value: AMERIFLUX_MCP_LOCAL__ROOTS=/data/fluxnet2015,/data/shared. The empty string, none and null mean "unset".
3. A YAML file passed with --config path.yaml, using the same section and field names.
4. Built-in defaults (the table below).

Unknown keys in the YAML file or the environment are ignored with a warning, so a typo does not stop the server but is visible in its log. Invalid values stop the server with exit code 2 and a message naming the setting and the rule, never the value you gave (so a mistyped email does not end up in a log). ameriflux-mcp does not load .env files itself; export the variables (set -a; . ./.env; set +a) before starting it.

The table at the end is generated from the code¹ (scripts/gen_config_reference.py); CI fails if it drifts.

The download identity¶

Identity is read from the environment or the YAML file only, never from flags or tool arguments, and is used only by the download tool. The plain names (AMERIFLUX_USER_ID, AMERIFLUX_USER_EMAIL, AMERIFLUX_USER_NAME, AMERIFLUX_INTENDED_USE, AMERIFLUX_DESCRIPTION) are what other AmeriFlux tools use; the namespaced AMERIFLUX_MCP_IDENTITY__… forms take precedence when set. AMERIFLUX_MCP_IDENTITY__IS_TEST has no plain form and no default. Look-alike names (AMERIFLUX_EMAIL, AMERIFLUX_USERNAME, AMERIFLUX_USER, AMERIFLUX_TOKEN, AMERIFLUX_API_KEY, AMF_USER_ID, AMF_USER_EMAIL, AMF_EMAIL) are not read; the server logs a warning, without the value, when one is set. See Download identity for what each value is and who sees it.

Command-line flags¶

A YAML example¶

# 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."
downloads:
  directory: /data/ameriflux-downloads
local:
  roots: [/data/fluxnet2015]          # FLUXNET2015 zips you downloaded from fluxnet.org
cache:
  disk_dir: /data/cache/ameriflux-mcp
server:
  log_level: info

Keep the user ID and email in the environment rather than in a YAML file you share or commit.

Automatic values¶

• downloads.enabled: off by default until AmeriFlux confirms third-party use of its download request. Set it to true (or pass --downloads) to list the download tool on stdio; over HTTP it is never listed, whatever this says. --no-downloads forces it off.
• cache.disk_dir: the on-disk cache is on for stdio and off for HTTP unless a directory is configured, so containers without a writable home still start.
• privacy.allow_contact_emails: off on every transport. Contact emails of tower teams and DOI contributors appear only when this is on and a tool call asks for contacts.

All settings¶