# ameriflux-mcp documentation — full corpus

Each page below begins with its canonical URL followed by its original Markdown, OKF frontmatter included.

---8<--- https://idss-mesa.github.io/ameriflux-mcp/getting-started/clients/

---
title: "Clients"
description: "Register ameriflux-mcp with Claude Code, Claude Desktop, Codex CLI, Gemini CLI, Goose, OpenCode and VS Code, or a hosted server over HTTP."
type: Guide
tags:
  - getting-started
  - clients
  - claude-code
  - codex
  - gemini
  - goose
generated:
  by: "claude/opus-5.5"
  at: "2026-10-23T00:00:00Z"
sources:
  - id: claude-code-mcp
    resource: "https://docs.claude.com/en/docs/claude-code/mcp"
    title: "Claude Code — MCP"
    author: "team:anthropic"
  - id: codex-mcp
    resource: "https://developers.openai.com/codex/cli/"
    title: "OpenAI Codex CLI"
    author: "team:openai"
  - id: gemini-mcp
    resource: "https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md"
    title: "Gemini CLI — MCP servers"
    author: "team:google"
  - id: goose-ext
    resource: "https://goose-docs.ai/docs/getting-started/using-extensions"
    title: "Goose — Using extensions"
    author: "team:block"
  - id: opencode-mcp
    resource: "https://opencode.ai/docs/mcp-servers/"
    title: "OpenCode — MCP servers"
    author: "team:opencode"
  - id: vscode-mcp
    resource: "https://code.visualstudio.com/docs/copilot/chat/mcp-servers"
    title: "VS Code — Use MCP servers"
    author: "team:microsoft"
status: draft
stale_after: "2027-04-23T00:00:00Z"
---

# Clients

Local clients start ameriflux-mcp themselves over **stdio**; hosted deployments are
reached over **Streamable HTTP**. The [install script](install.md#option-1-from-source-with-the-install-script-recommended)
(`scripts/install.sh`) writes the stdio entries below for Claude Code, Claude Desktop,
Codex CLI, Gemini CLI, Goose and OpenCode in one step; this page shows them for manual
setup. The examples use `ameriflux-mcp` on your `PATH` (see [Install](install.md));
replace it with an absolute path such as
`/home/me/ameriflux-mcp/.venv/bin/ameriflux-mcp` (Windows:
`C:\\Users\\me\\ameriflux-mcp\\.venv\\Scripts\\ameriflux-mcp.exe`) when the client does
not share your shell's `PATH`. JSON-configured clients do not expand `~` or `$HOME`, so
use absolute paths there.

The examples register the server **without** a download identity, which is all that
discovery, variables, citations and local previews need. To enable downloads, add the
variables from [Download identity](identity.md#the-settings) to the same `env` block
(or `-e` options); keep them in the client's environment settings, never in a shared or
committed file.

## Claude Code

```bash
claude mcp add ameriflux -s user -- ameriflux-mcp --transport stdio
claude mcp list
```

`-s user` makes the server available in every project[^claude-code-mcp]. Add
`-e NAME=value` options before `--` for the download identity.

## Claude Desktop

Edit `claude_desktop_config.json` and restart the app:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ameriflux": {
      "command": "/absolute/path/to/ameriflux-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}
```

## Codex CLI

```bash
codex mcp add ameriflux -- ameriflux-mcp --transport stdio
codex mcp list
```

This writes the server into `~/.codex/config.toml`[^codex-mcp]; restart running
sessions. Without the CLI, add the table yourself:

```toml
[mcp_servers.ameriflux]
command = "/absolute/path/to/ameriflux-mcp"
args = []

# only for downloads:
# [mcp_servers.ameriflux.env]
# AMERIFLUX_USER_ID = "your-username"
```

## Gemini CLI

```bash
gemini mcp add --scope user ameriflux ameriflux-mcp
gemini mcp list
```

or add the entry to `~/.gemini/settings.json`[^gemini-mcp] (`.gemini/settings.json` in a
project):

```json
{
  "mcpServers": {
    "ameriflux": {
      "command": "/absolute/path/to/ameriflux-mcp",
      "args": []
    }
  }
}
```

## Goose

Add an extension to `~/.config/goose/config.yaml` (Windows:
`%APPDATA%\Block\goose\config\config.yaml`)[^goose-ext], then restart Goose Desktop or
start a new CLI session. `goose configure` → *Add Extension* → *Command-line Extension*
does the same interactively.

```yaml
extensions:
  ameriflux:
    enabled: true
    type: stdio
    name: ameriflux
    cmd: /absolute/path/to/ameriflux-mcp
    args: []
    envs: {}
    timeout: 300
```

## OpenCode

Add to `~/.config/opencode/opencode.json`[^opencode-mcp]. This is the layout OpenCode's
documentation shows. The install script writes `"mcp": {"servers": {…}}` instead unless
`opencode --version` reports 1.x; if your OpenCode does not pick the server up, move the
entry to the layout its documentation gives.

```json
{
  "mcp": {
    "ameriflux": {
      "type": "local",
      "command": ["/absolute/path/to/ameriflux-mcp", "--transport", "stdio"],
      "enabled": true
    }
  }
}
```

## VS Code

Add to `.vscode/mcp.json` in a workspace, or to your user configuration[^vscode-mcp].
For downloads, `inputs` prompts keep your identity out of the file:

```json
{
  "inputs": [
    { "type": "promptString", "id": "amf-user", "description": "AmeriFlux user ID" },
    { "type": "promptString", "id": "amf-email", "description": "Email registered with AmeriFlux", "password": true }
  ],
  "servers": {
    "ameriflux": {
      "type": "stdio",
      "command": "/absolute/path/to/ameriflux-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "AMERIFLUX_USER_ID": "${input:amf-user}",
        "AMERIFLUX_USER_EMAIL": "${input:amf-email}"
      }
    }
  }
}
```

Leave out `inputs` and `env` to run without downloads.

## Any other stdio client

Run `ameriflux-mcp --transport stdio` (bare `ameriflux-mcp` does the same), with the
download identity in the environment if you want downloads. The server speaks MCP
2026-07-28 and still accepts clients on earlier protocol revisions over stdio.

## A hosted server (HTTP)

```bash
claude mcp add --transport http ameriflux https://ameriflux-mcp.example.org/mcp
```

A hosted server offers the eight tools that need no identity and read no local files:
site search, site details, availability, the two variable tools, citations, BADM and
`amf_ping`. Downloads and the local file tools exist only on stdio, and no identity is
accepted over HTTP, by header or otherwise.

[^claude-code-mcp]: Claude Code — MCP. <https://docs.claude.com/en/docs/claude-code/mcp>
[^codex-mcp]: OpenAI Codex CLI. <https://developers.openai.com/codex/cli/>
[^gemini-mcp]: Gemini CLI — MCP servers. <https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md>
[^goose-ext]: Goose — Using extensions. <https://goose-docs.ai/docs/getting-started/using-extensions>
[^opencode-mcp]: OpenCode — MCP servers. <https://opencode.ai/docs/mcp-servers/>
[^vscode-mcp]: VS Code — Use MCP servers. <https://code.visualstudio.com/docs/copilot/chat/mcp-servers>

---8<--- https://idss-mesa.github.io/ameriflux-mcp/getting-started/configuration/

---
title: "Configuration"
description: "Configure ameriflux-mcp with a YAML file, AMERIFLUX_MCP_ environment variables or flags; precedence rules and every setting with its default."
type: Reference
tags:
  - getting-started
  - configuration
  - environment
generated:
  by: "claude/opus-5.5"
  at: "2026-10-23T00:00:00Z"
sources:
  - id: config-module
    resource: "https://github.com/idss-mesa/ameriflux-mcp/blob/main/src/ameriflux_mcp/config.py"
    title: "ameriflux-mcp configuration model (config.py)"
    author: "team:idss-mesa"
  - id: design
    resource: "https://github.com/idss-mesa/ameriflux-mcp/blob/main/DESIGN.md"
    title: "ameriflux-mcp design (decisions D12, D17-D23, D25)"
    author: "team:idss-mesa"
status: stable
stale_after: "2027-04-23T00:00:00Z"
---

# 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[^config-module]
(`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](identity.md) for what each value is and who sees it.

## Command-line flags

| Flag | Sets |
| --- | --- |
| `--config PATH` | YAML file to load |
| `--transport {stdio,http}` | `server.transport` |
| `--bind-address`, `--bind-port` | `server.bind_address`, `server.bind_port` |
| `--log-level` | `server.log_level` |
| `--download-dir PATH` | `downloads.directory` |
| `--downloads` | `downloads.enabled = true` (stdio only) |
| `--no-downloads` | `downloads.enabled = false` |
| `--print-config` | print the effective configuration as YAML (identity shown as `***`) and exit |
| `--check` | load the configuration, call `amf_ping` in-process (no network request), print a JSON report, exit 0 or 1 |
| `--version` | print the version |

## A YAML example

```yaml
# 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

<!-- BEGIN GENERATED CONFIG (scripts/gen_config_reference.py; do not edit) -->

| Setting (YAML path) | Environment variable | Type | Default | Description |
| --- | --- | --- | --- | --- |
| `upstream.api_base_url` | `AMERIFLUX_MCP_UPSTREAM__API_BASE_URL` | str | `https://amfcdn.lbl.gov/api` | AmeriFlux API base URL (v1 and v2 paths are appended per endpoint). |
| `upstream.user_agent_suffix` | `AMERIFLUX_MCP_UPSTREAM__USER_AGENT_SUFFIX` | str \| null | unset | Text appended to the User-Agent header. |
| `upstream.connect_timeout_s` | `AMERIFLUX_MCP_UPSTREAM__CONNECT_TIMEOUT_S` | float | `10.0` | TCP/TLS connect timeout. |
| `upstream.read_timeout_s` | `AMERIFLUX_MCP_UPSTREAM__READ_TIMEOUT_S` | float | `60.0` | Default read timeout. |
| `upstream.download_read_timeout_s` | `AMERIFLUX_MCP_UPSTREAM__DOWNLOAD_READ_TIMEOUT_S` | float | `300.0` | Read timeout for data file downloads. |
| `upstream.requests_per_second` | `AMERIFLUX_MCP_UPSTREAM__REQUESTS_PER_SECOND` | float | `2.0` | Rate limit towards the AmeriFlux API (local policy). |
| `upstream.max_concurrency` | `AMERIFLUX_MCP_UPSTREAM__MAX_CONCURRENCY` | int | `4` | Maximum simultaneous upstream requests. |
| `upstream.max_response_bytes` | `AMERIFLUX_MCP_UPSTREAM__MAX_RESPONSE_BYTES` | int | `20971520` | Largest upstream response body read into memory (the site catalog is 1.7 MB). |
| `upstream.retries.max_attempts` | `AMERIFLUX_MCP_UPSTREAM__RETRIES__MAX_ATTEMPTS` | int | `3` | Attempts per upstream call, including the first. |
| `upstream.retries.backoff_base_s` | `AMERIFLUX_MCP_UPSTREAM__RETRIES__BACKOFF_BASE_S` | float | `0.5` | Base of the exponential backoff (0.5 * 2^n seconds). |
| `upstream.retries.backoff_max_s` | `AMERIFLUX_MCP_UPSTREAM__RETRIES__BACKOFF_MAX_S` | float | `8.0` | Cap on a single backoff sleep. |
| `upstream.retries.retry_after_default_s` | `AMERIFLUX_MCP_UPSTREAM__RETRIES__RETRY_AFTER_DEFAULT_S` | float | `1.0` | Wait used on HTTP 429 when no Retry-After header is sent. |
| `identity.user_id` | `AMERIFLUX_MCP_IDENTITY__USER_ID`<br>(or `AMERIFLUX_USER_ID`) | SecretStr \| null | unset | AmeriFlux username sent with downloads (or AMERIFLUX_USER_ID). |
| `identity.user_email` | `AMERIFLUX_MCP_IDENTITY__USER_EMAIL`<br>(or `AMERIFLUX_USER_EMAIL`) | SecretStr \| null | unset | Email registered with AmeriFlux, sent with downloads (or AMERIFLUX_USER_EMAIL). |
| `identity.user_name` | `AMERIFLUX_MCP_IDENTITY__USER_NAME`<br>(or `AMERIFLUX_USER_NAME`) | SecretStr \| null | unset | Optional name sent with downloads (or AMERIFLUX_USER_NAME). |
| `identity.profiles.<name>.intended_use` | `AMERIFLUX_MCP_IDENTITY__PROFILES__<NAME>__INTENDED_USE`<br>(default profile: `AMERIFLUX_INTENDED_USE`) | `synthesis` \| `model` \| `remote_sensing` \| `other_research` \| `education` \| `other` \| null | unset | Intended-use category: 1-6 or synthesis, model, remote_sensing, other_research, education, other. |
| `identity.profiles.<name>.description` | `AMERIFLUX_MCP_IDENTITY__PROFILES__<NAME>__DESCRIPTION`<br>(default profile: `AMERIFLUX_DESCRIPTION`) | str \| null | unset | How you will use the data, in your own words (20-1000 characters); ' [ameriflux-mcp]' is appended when sent. |
| `identity.is_test` | `AMERIFLUX_MCP_IDENTITY__IS_TEST` | bool \| null | unset | Send downloads as test requests. Must be set before any download. |
| `cache.enabled` | `AMERIFLUX_MCP_CACHE__ENABLED` | bool | `true` | Cache AmeriFlux API responses. |
| `cache.max_entries` | `AMERIFLUX_MCP_CACHE__MAX_ENTRIES` | int | `1024` | Overall in-memory entry cap. |
| `cache.stale_if_error_s` | `AMERIFLUX_MCP_CACHE__STALE_IF_ERROR_S` | int | `604800` | How long an expired entry may be served when a refresh fails. |
| `cache.disk_dir` | `AMERIFLUX_MCP_CACHE__DISK_DIR` | Path \| null | unset | On-disk cache (personal fields removed). Unset: ~/.cache/ameriflux-mcp on stdio, none over http. |
| `cache.ttl_s.catalog` | `AMERIFLUX_MCP_CACHE__TTL_S__CATALOG` | int | `21600` | Site catalog (6 h). |
| `cache.ttl_s.availability` | `AMERIFLUX_MCP_CACHE__TTL_S__AVAILABILITY` | int | `21600` | Availability lists (6 h). |
| `cache.ttl_s.fluxnet2015` | `AMERIFLUX_MCP_CACHE__TTL_S__FLUXNET2015` | int | `2592000` | Frozen FLUXNET2015 and FLUXNET-CH4 lists (30 d). |
| `cache.ttl_s.variables` | `AMERIFLUX_MCP_CACHE__TTL_S__VARIABLES` | int | `86400` | FP Standard variable list (24 h). |
| `cache.ttl_s.citations` | `AMERIFLUX_MCP_CACHE__TTL_S__CITATIONS` | int | `86400` | DOI citations (24 h, memory only). |
| `cache.ttl_s.dictionaries` | `AMERIFLUX_MCP_CACHE__TTL_S__DICTIONARIES` | int | `2592000` | FLUXNET variable dictionaries (30 d). |
| `cache.ttl_s.heights` | `AMERIFLUX_MCP_CACHE__TTL_S__HEIGHTS` | int | `86400` | Measurement heights (24 h). |
| `cache.ttl_s.coverage` | `AMERIFLUX_MCP_CACHE__TTL_S__COVERAGE` | int | `604800` | Variable coverage snapshots (7 d). |
| `limits.default_limit` | `AMERIFLUX_MCP_LIMITS__DEFAULT_LIMIT` | int | `25` | Default page size where a tool does not set its own. |
| `limits.max_limit` | `AMERIFLUX_MCP_LIMITS__MAX_LIMIT` | int | `200` | Largest page size any tool accepts. |
| `limits.max_result_bytes` | `AMERIFLUX_MCP_LIMITS__MAX_RESULT_BYTES` | int | `50000` | Tool results are trimmed (with page.truncated) to fit this many bytes of compact JSON. |
| `limits.hard_max_result_bytes` | `AMERIFLUX_MCP_LIMITS__HARD_MAX_RESULT_BYTES` | int | `200000` | A result still larger than this after trimming fails with result_too_large. |
| `limits.max_resource_bytes` | `AMERIFLUX_MCP_LIMITS__MAX_RESOURCE_BYTES` | int | `1048576` | Largest resource read returned; larger ones fail with result_too_large. |
| `limits.preview_max_rows` | `AMERIFLUX_MCP_LIMITS__PREVIEW_MAX_ROWS` | int | `500` | Most rows amf_preview_data returns. |
| `limits.preview_scan_max_bytes` | `AMERIFLUX_MCP_LIMITS__PREVIEW_SCAN_MAX_BYTES` | int | `268435456` | Most bytes a preview scans (256 MiB). |
| `limits.preview_time_budget_s` | `AMERIFLUX_MCP_LIMITS__PREVIEW_TIME_BUDGET_S` | float | `20.0` | Wall-clock budget for one preview scan. |
| `limits.zip_member_max_bytes` | `AMERIFLUX_MCP_LIMITS__ZIP_MEMBER_MAX_BYTES` | int | `1073741824` | Largest zip member read (uncompressed). |
| `limits.tools_list_max_bytes` | `AMERIFLUX_MCP_LIMITS__TOOLS_LIST_MAX_BYTES` | int | `85000` | Conformance bound on the serialized tools/list result: 67,948 B measured with the 12 stdio tools of v0.1.0, x1.25 (as neon-mcp). |
| `downloads.enabled` | `AMERIFLUX_MCP_DOWNLOADS__ENABLED` | bool | `false` | Offer the download tool (stdio only; never over http). Off by default until AmeriFlux confirms third-party use of its download request (research/questions.md Q1). |
| `downloads.directory` | `AMERIFLUX_MCP_DOWNLOADS__DIRECTORY` | Path | `~/ameriflux-downloads` | Directory every download is confined to (created on first use). |
| `downloads.max_files_per_call` | `AMERIFLUX_MCP_DOWNLOADS__MAX_FILES_PER_CALL` | int | `50` | Most files one download call transfers. |
| `downloads.max_bytes_per_call` | `AMERIFLUX_MCP_DOWNLOADS__MAX_BYTES_PER_CALL` | int | `2147483648` | Most bytes one download call transfers (2 GiB). |
| `downloads.max_file_bytes` | `AMERIFLUX_MCP_DOWNLOADS__MAX_FILE_BYTES` | int | `1073741824` | Largest single file accepted (1 GiB). |
| `local.roots` | `AMERIFLUX_MCP_LOCAL__ROOTS` | list[Path] | `[]` | Extra directories the local file tools may read (the download directory is always included), e.g. FLUXNET2015 zips from fluxnet.org. |
| `privacy.allow_contact_emails` | `AMERIFLUX_MCP_PRIVACY__ALLOW_CONTACT_EMAILS` | bool | `false` | Allow team and contributor emails in results when a call asks for contacts. |
| `server.transport` | `AMERIFLUX_MCP_SERVER__TRANSPORT` | `stdio` \| `http` | `stdio` | stdio (local clients) or http (stateless Streamable HTTP at /mcp). |
| `server.bind_address` | `AMERIFLUX_MCP_SERVER__BIND_ADDRESS` | str | `127.0.0.1` | HTTP bind address. |
| `server.bind_port` | `AMERIFLUX_MCP_SERVER__BIND_PORT` | int | `8080` | HTTP bind port. |
| `server.public_base_url` | `AMERIFLUX_MCP_SERVER__PUBLIC_BASE_URL` | str \| null | unset | Public URL of a hosted deployment; its host/origin join the allow-lists. |
| `server.allowed_hosts` | `AMERIFLUX_MCP_SERVER__ALLOWED_HOSTS` | list[str] | `[]` | Host header allow-list (DNS-rebinding protection). |
| `server.allowed_origins` | `AMERIFLUX_MCP_SERVER__ALLOWED_ORIGINS` | list[str] | `[]` | Origin header allow-list (DNS-rebinding protection). |
| `server.dns_rebinding_protection` | `AMERIFLUX_MCP_SERVER__DNS_REBINDING_PROTECTION` | bool \| null | unset | Force DNS-rebinding protection on/off. Unset: SDK default (on for loopback binds or when allow-lists are set). |
| `server.json_response` | `AMERIFLUX_MCP_SERVER__JSON_RESPONSE` | bool | `false` | Answer POST /mcp with application/json instead of a single SSE frame. |
| `server.max_request_body_size` | `AMERIFLUX_MCP_SERVER__MAX_REQUEST_BODY_SIZE` | int | `1048576` | Largest accepted request body in bytes. |
| `server.tools_list_ttl_ms` | `AMERIFLUX_MCP_SERVER__TOOLS_LIST_TTL_MS` | int | `300000` | ttlMs advertised on tools/list. |
| `server.log_level` | `AMERIFLUX_MCP_SERVER__LOG_LEVEL` | `debug` \| `info` \| `warning` \| `error` \| `critical` | `info` | Log verbosity. |
| `server.instructions_extra` | `AMERIFLUX_MCP_SERVER__INSTRUCTIONS_EXTRA` | str \| null | unset | Text appended to the server instructions. |

<!-- END GENERATED CONFIG -->

[^config-module]: ameriflux-mcp configuration model. <https://github.com/idss-mesa/ameriflux-mcp/blob/main/src/ameriflux_mcp/config.py>

---8<--- https://idss-mesa.github.io/ameriflux-mcp/getting-started/identity/

---
title: "Download identity"
description: "What AmeriFlux downloads disclose, how to create an account, and how to give ameriflux-mcp your user ID, email and intended use."
type: Guide
tags:
  - getting-started
  - identity
  - downloads
  - data-policy
  - privacy
generated:
  by: "claude/opus-5.5"
  at: "2026-10-23T00:00:00Z"
sources:
  - id: amf-policy
    resource: "https://ameriflux.lbl.gov/data/data-policy/"
    title: "AmeriFlux Data Policy"
    author: "team:ameriflux"
  - id: amf-account
    resource: "https://amfcdn.lbl.gov/create"
    title: "FLUX User Account Creation (AmeriFlux and FLUXNET)"
    author: "team:ameriflux"
  - id: fluxnet-policy
    resource: "https://fluxnet.org/data/data-policy/"
    title: "FLUXNET Data Policy"
    author: "team:fluxnet"
  - id: research
    resource: "https://github.com/idss-mesa/ameriflux-mcp/blob/main/RESEARCH.md"
    title: "ameriflux-mcp verified research (section 5, downloads)"
    author: "team:idss-mesa"
status: draft
stale_after: "2027-04-23T00:00:00Z"
---

# 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.

!!! info "Used by amf_download_data, which is off by default"

    The download tool is the only part of ameriflux-mcp that uses the identity.
    Downloads are **off by default** until AmeriFlux confirms that third-party clients may use its download request (question Q1 in the project's [support questions](https://github.com/idss-mesa/ameriflux-mcp/blob/main/research/questions.md){target=_blank}). Turn it on with `AMERIFLUX_MCP_DOWNLOADS__ENABLED=true`.
    [Downloads](../tools/downloads.md) walks through the plan, the consent call and what
    is written to disk.

## 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)[^amf-policy]. 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](https://amfcdn.lbl.gov/create){target=_blank} page[^amf-account]:
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[^research] (question Q2
in the project's [support questions](https://github.com/idss-mesa/ameriflux-mcp/blob/main/research/questions.md){target=_blank}).

## The settings

| Setting | Environment variable | Required | Notes |
| --- | --- | --- | --- |
| User ID | `AMERIFLUX_USER_ID` | yes | Your AmeriFlux username. |
| Email | `AMERIFLUX_USER_EMAIL` | yes | The email registered with AmeriFlux. |
| Name | `AMERIFLUX_USER_NAME` | no | Shown to PIs alongside your email. |
| Intended use | `AMERIFLUX_INTENDED_USE` | yes | A code from the table below. |
| Description | `AMERIFLUX_DESCRIPTION` | yes | 20–1000 characters, in your own words. |
| Test requests | `AMERIFLUX_MCP_IDENTITY__IS_TEST` | yes | `true` or `false`; no default (see [below](#is_test)). |

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:

| Code | Key | Category sent to AmeriFlux |
| --- | --- | --- |
| 1 | `synthesis` | Research - Multi-site synthesis |
| 2 | `model` | Research - Land model/Earth system model |
| 3 | `remote_sensing` | Research - Remote sensing |
| 4 | `other_research` | Research - Other |
| 5 | `education` | Education (Teacher or Student) |
| 6 | `other` | Other |

**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:

```yaml
# 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

=== "Install script"

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

    The script reads the variables from your environment or asks for each missing one,
    validates them, and stores them in every agent's server `env`, with owner-only file
    permissions. See [Install](install.md#the-download-identity-and-the-script).

=== "Claude Code"

    ```bash
    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
    ```

=== "JSON clients"

    ```json
    {
      "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[^amf-policy]. FLUXNET2015 uses Tier 1 (CC-BY-4.0) and Tier 2[^fluxnet-policy].
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](../about/citing-ameriflux.md) 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](configuration.md)), 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.

[^amf-policy]: AmeriFlux Data Policy. <https://ameriflux.lbl.gov/data/data-policy/>
[^amf-account]: FLUX User Account Creation. <https://amfcdn.lbl.gov/create>
[^fluxnet-policy]: FLUXNET Data Policy. <https://fluxnet.org/data/data-policy/>
[^research]: ameriflux-mcp verified research. <https://github.com/idss-mesa/ameriflux-mcp/blob/main/RESEARCH.md>

---8<--- https://idss-mesa.github.io/ameriflux-mcp/getting-started/install/

---
title: "Install ameriflux-mcp"
description: "Install ameriflux-mcp on macOS, Linux or Windows with uv and the install script, register it by hand, verify, upgrade or remove it."
type: Guide
tags:
  - getting-started
  - install
  - uv
  - install-script
  - windows
generated:
  by: "claude/opus-5.5"
  at: "2026-10-24T00:00:00Z"
sources:
  - id: uv
    resource: "https://docs.astral.sh/uv/"
    title: "uv documentation"
    author: "team:astral"
  - id: uv-install
    resource: "https://docs.astral.sh/uv/getting-started/installation/"
    title: "Installing uv"
    author: "team:astral"
  - id: gh
    resource: "https://cli.github.com/"
    title: "GitHub CLI"
    author: "team:github"
  - id: repo
    resource: "https://github.com/idss-mesa/ameriflux-mcp"
    title: "ameriflux-mcp source repository"
    author: "team:idss-mesa"
status: draft
stale_after: "2027-04-23T00:00:00Z"
---

# Install ameriflux-mcp

ameriflux-mcp is a Python 3.11+ package with one command, `ameriflux-mcp`, that MCP
clients start over stdio. These instructions cover macOS, Linux and Windows.

!!! note "Private repository; PyPI from the v0.1.0 tag"

    The repository is private for now, so you need read access to
    [idss-mesa/ameriflux-mcp](https://github.com/idss-mesa/ameriflux-mcp){target=_blank}[^repo]
    and git credentials (see [Access the repository](#access-the-repository)). The
    package is published to PyPI as `ameriflux-mcp` when v0.1.0 is tagged; until then,
    install from the repository.

## Prerequisites

- [uv](https://docs.astral.sh/uv/){target=_blank}[^uv], which installs Python 3.11+ for
  ameriflux-mcp if your system lacks it and keeps the server in its own environment.
- git, to clone the repository.
- Access to the private repository on GitHub, for example through the
  [GitHub CLI](https://cli.github.com/){target=_blank}[^gh].
- Optional: an [AmeriFlux account](identity.md), only for downloading data. Everything
  else works without one.

### Install uv

=== "macOS"

    ```bash
    curl -LsSf https://astral.sh/uv/install.sh | sh
    # or: brew install uv
    ```

=== "Linux"

    ```bash
    curl -LsSf https://astral.sh/uv/install.sh | sh
    # or your distribution's package, if it ships uv 0.5 or newer
    ```

=== "Windows (PowerShell)"

    ```powershell
    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
    # or: winget install --id=astral-sh.uv -e
    ```

Open a new terminal afterwards so `uv` is on your `PATH`, and check with
`uv --version`[^uv-install].

### Install git

=== "macOS"

    ```bash
    xcode-select --install        # Apple's command-line tools include git
    # or: brew install git
    ```

=== "Linux"

    ```bash
    sudo apt install git          # Debian, Ubuntu
    sudo dnf install git          # Fedora, RHEL
    ```

=== "Windows"

    ```powershell
    winget install --id Git.Git -e
    ```

    Git for Windows includes **Git Bash**, which the install script needs on Windows.

### Access the repository

While the repository is private, clone it with credentials GitHub accepts. The GitHub
CLI is the simplest route on every platform:

=== "macOS"

    ```bash
    brew install gh
    gh auth login                 # choose GitHub.com, HTTPS, and log in with a browser
    ```

=== "Linux"

    ```bash
    # install gh from https://cli.github.com/ (packages for apt, dnf, zypper, ...)
    gh auth login
    ```

=== "Windows (PowerShell)"

    ```powershell
    winget install --id GitHub.cli -e
    gh auth login
    ```

`gh auth login` also sets up git's credential helper, so plain `git clone https://…`
and `uv tool install git+https://…` work afterwards. An SSH key added to your GitHub
account works too: clone `git@github.com:idss-mesa/ameriflux-mcp.git` instead.

## Option 1: From source with the install script (recommended)

=== "macOS / Linux"

    ```bash
    git clone https://github.com/idss-mesa/ameriflux-mcp.git
    cd ameriflux-mcp
    scripts/install.sh
    ```

=== "Windows (Git Bash)"

    ```bash
    git clone https://github.com/idss-mesa/ameriflux-mcp.git
    cd ameriflux-mcp
    scripts/install.sh --dry-run    # check the paths it will write first
    scripts/install.sh
    ```

`scripts/install.sh` creates the server environment (`uv sync`) if
`.venv/bin/ameriflux-mcp` is missing, checks that `ameriflux-mcp --version` runs, then
registers that executable with every supported agent it finds on your machine: Claude
Code, Claude Desktop, OpenAI Codex CLI, Gemini CLI, Goose and OpenCode. It prefers each
agent's own CLI when one is installed (`claude mcp add`, `codex mcp add`,
`gemini mcp add`) and otherwise merges an entry into the agent's config file, keeping
everything else in the file and leaving a `.bak` copy.

```bash
scripts/install.sh --with-identity               # also store your download identity (see below)
scripts/install.sh --agents all --dry-run        # preview the change for every agent
scripts/install.sh --agents claude,goose         # just Claude Code and Goose
scripts/install.sh --scope project               # project-level config (claude, codex, gemini, opencode)
scripts/install.sh --env AMERIFLUX_MCP_SERVER__LOG_LEVEL=debug   # any extra environment variable
scripts/install.sh --command "$(command -v ameriflux-mcp)"       # register a uv-tool install instead
scripts/install.sh --uninstall                   # remove the registration everywhere
```

| Agent | What the script does |
| --- | --- |
| `claude` (Claude Code) | `claude mcp add --scope user ameriflux -- /path/to/ameriflux-mcp/.venv/bin/ameriflux-mcp` |
| `claude-desktop` | adds `mcpServers.ameriflux` to `claude_desktop_config.json` |
| `codex` (OpenAI Codex CLI) | `codex mcp add ameriflux -- …`, or an `[mcp_servers.ameriflux]` table in `~/.codex/config.toml` |
| `gemini` (Gemini CLI) | `gemini mcp add --scope user ameriflux …`, or `mcpServers.ameriflux` in `~/.gemini/settings.json` |
| `goose` | adds an `ameriflux` stdio extension to `~/.config/goose/config.yaml` |
| `opencode` | adds `mcp.servers.ameriflux` (v2) or `mcp.ameriflux` (v1) to `~/.config/opencode/opencode.json` |

The script writes the absolute path of the executable, because desktop apps do not
inherit your shell `PATH`. It needs bash; macOS's built-in bash 3.2 is enough. Restart
desktop apps (Claude Desktop, Goose Desktop) after installing.

### The download identity and the script

Only the download tool needs an identity, and everything in it is sent to the site
PIs when you confirm a download ([Download identity](identity.md) explains why). There
is deliberately no option that takes these values on the command line, since command
lines end up in shell history and process lists. `--with-identity` reads them from your
environment, or asks for each missing one on a terminal:

```bash
scripts/install.sh --with-identity
# AmeriFlux user ID: ...
# Email registered with AmeriFlux: ...
# Your name (optional, Enter to skip):
# Intended use (1 synthesis, 2 model, 3 remote sensing, 4 other research, 5 education, 6 other): ...
# Describe how you will use the data (20-1000 characters, in your own words): ...
# Send downloads as test requests? (true/false): ...
```

The answers are stored in each agent's server `env` as `AMERIFLUX_USER_ID`,
`AMERIFLUX_USER_EMAIL`, `AMERIFLUX_USER_NAME`, `AMERIFLUX_INTENDED_USE`,
`AMERIFLUX_DESCRIPTION` and `AMERIFLUX_MCP_IDENTITY__IS_TEST`.

- They are stored **in plain text** in each agent's config file. The script restricts
  the files it writes, and their `.bak` copies, to your user (mode `600`), and masks your
  user ID, email and name as `***` in everything it prints, including the output of the
  agent CLIs it calls.
- For agents registered through their own CLI (Claude Code, Codex, Gemini CLI), the
  values are passed to that CLI's `mcp add` command and are briefly visible in the
  process list. Add `--prefer-files` to have Codex and Gemini CLI configured by file.
- Without `--with-identity` nothing is stored. Discovery, availability, variables,
  citations and local previews work as usual; the download tool explains what is
  missing when you ask it to download.

### Windows

On Windows, run the script from **Git Bash** (installed with Git for Windows) or
register by hand (Option 2). Git Bash converts paths to Windows form, uses
`.venv\Scripts\ameriflux-mcp.exe`, and writes Claude Desktop's config under
`%APPDATA%\Claude` and Goose's under `%APPDATA%\Block\goose\config`. Git Bash support
has not been tested as widely as macOS and Linux; check the result with `--dry-run`
first. Do not run the script inside WSL to configure Windows apps: it would write WSL's
own config files, which Claude Desktop for Windows never reads. (Inside WSL, for agents
that also run inside WSL, it works as on Linux.)

## Option 2: Install the package and register it by hand

=== "uv tool (recommended)"

    ```bash
    uv tool install git+https://github.com/idss-mesa/ameriflux-mcp
    ```

    This puts `ameriflux-mcp` in uv's tool directory (`~/.local/bin` on macOS and
    Linux, `%USERPROFILE%\.local\bin` on Windows) and uses your git credentials for the
    private repository. Upgrade with
    `uv tool install --reinstall git+https://github.com/idss-mesa/ameriflux-mcp`.

=== "From source"

    ```bash
    git clone https://github.com/idss-mesa/ameriflux-mcp.git
    cd ameriflux-mcp
    uv sync                      # creates .venv with the package
    uv run ameriflux-mcp --version
    ```

=== "PyPI (from v0.1.0)"

    ```bash
    uv tool install ameriflux-mcp
    # or: pipx install ameriflux-mcp
    ```

    Available once v0.1.0 is tagged and published; until then use the repository.

Then find the executable's absolute path, which is what desktop apps need:

=== "macOS / Linux"

    ```bash
    command -v ameriflux-mcp     # e.g. /Users/you/.local/bin/ameriflux-mcp
    # from source: /path/to/ameriflux-mcp/.venv/bin/ameriflux-mcp
    ```

=== "Windows (PowerShell)"

    ```powershell
    (Get-Command ameriflux-mcp).Source  # e.g. C:\Users\you\.local\bin\ameriflux-mcp.exe
    # from source: C:\path\to\ameriflux-mcp\.venv\Scripts\ameriflux-mcp.exe
    ```

and register it with your client. The shortest form, for Claude Code:

```bash
claude mcp add ameriflux -s user -- ameriflux-mcp
```

Claude Desktop, and other JSON-configured clients:

```json
{
  "mcpServers": {
    "ameriflux": {
      "command": "/ABSOLUTE/PATH/TO/ameriflux-mcp",
      "args": []
    }
  }
}
```

Use absolute paths (not `~/` or `./`). On Windows escape backslashes:
`"C:\\Users\\You\\.local\\bin\\ameriflux-mcp.exe"`. To enable downloads, add an `env`
block with your identity ([Download identity](identity.md#give-it-to-ameriflux-mcp)).
[Clients](clients.md) has the entries for Claude Desktop, Codex CLI, Gemini CLI, Goose,
OpenCode, VS Code and hosted servers.

## Option 3: Docker

The repository ships a `Dockerfile` that serves stateless Streamable HTTP on port 8080
as a non-root user (uid 10001), with `/healthz` and `/readyz` and a container health
check:

```bash
git clone https://github.com/idss-mesa/ameriflux-mcp.git && cd ameriflux-mcp
docker build -t ameriflux-mcp .
docker run --rm --read-only --tmpfs /tmp -p 127.0.0.1:8080:8080 ameriflux-mcp
```

Or `docker compose up -d` with the repository's `docker-compose.yml` (bound to
127.0.0.1; set `PUBLIC_BASE_URL` and `ALLOWED_HOSTS` behind a TLS proxy). Point an
HTTP-capable client at `http://127.0.0.1:8080/mcp`; `curl -s localhost:8080/healthz`
answers `200`. Over HTTP the server offers the eight discovery, variable, citation and
BADM tools and the prompts; downloads and local file tools are stdio only, and no
identity is ever accepted over HTTP.

## Verify the installation

```bash
ameriflux-mcp --version     # ameriflux-mcp 0.1.0
ameriflux-mcp --check       # {"ok": true, "version": "0.1.0", "protocolVersion": "2026-07-28", "transport": "stdio", "identityConfigured": false, "downloadsEnabled": false}
```

`--check` loads your configuration, calls `amf_ping` in-process and prints a one-line
JSON report: version, protocol, transport, whether a download identity is configured
(as booleans, never the values) and whether downloads are enabled. It makes no network
request. To check that AmeriFlux answers, ask your agent to call `amf_ping` with
`check_api=true` once the server is connected. `--print-config` shows the effective
settings with identity values replaced by `***`.

In Claude Code, `claude mcp list` runs a health check and shows `ameriflux` as
connected. To talk to the server directly over stdio:

```bash
# 2026-07-28 client: every request carries the protocol envelope in _meta
echo '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"manual","version":"0"}}}}' \
  | ameriflux-mcp

# 2025-era client: classic initialize handshake, then tools/list
printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | ameriflux-mcp
```

Both print JSON-RPC responses on stdout (logs go to stderr) and exit once stdin closes.
`server/discover` reports the server's capabilities and instructions; `tools/list` lists
every tool available in that build.

## Configuration

Nothing is required. The settings most people touch:

```bash
AMERIFLUX_MCP_SERVER__LOG_LEVEL=info           # debug | info | warning | error | critical (stderr)
AMERIFLUX_MCP_DOWNLOADS__DIRECTORY=            # where downloads go (default ~/ameriflux-downloads)
AMERIFLUX_MCP_LOCAL__ROOTS=                    # extra folders the file tools may read (e.g. FLUXNET2015 zips)
AMERIFLUX_MCP_DOWNLOADS__ENABLED=true          # offer the download tool (off by default)
```

ameriflux-mcp does not read `.env` files on its own. See [Configuration](configuration.md)
for every setting, the YAML file and the precedence rules.

## Troubleshooting

**The install script says "nothing was registered".** `ameriflux-mcp --version` did not
run, so the script refused to register a broken command. Run `uv sync` in the clone (or
reinstall with `uv tool install --reinstall …`) and try again; run the command yourself
to see its error; `scripts/install.sh --dry-run` shows what it would do without stopping.

**The server exits at once with "invalid configuration".** A setting failed validation
(exit code 2). The message names the setting and the rule, for example
`identity.user_email: Value error, user_email is not an email address`; it never repeats
the value, so check the variable yourself. `ameriflux-mcp --print-config` shows the
effective settings once they load.

**`git clone` fails with "Repository not found" or asks for a password.** The repository
is private: GitHub answers 404 to anyone without access. Ask an idss-mesa maintainer for
access, then run `gh auth login` (or use SSH) so git sends your credentials.

**`ameriflux-mcp: command not found` from a desktop app.** Desktop apps do not read your
shell profile. Use the executable's absolute path as the `command`; the install script
does this for you.

**Server shows as disconnected.** Run the configured command yourself with `--check`. If
it fails, re-create the environment (`uv sync` in a clone, or
`uv tool install --reinstall git+https://github.com/idss-mesa/ameriflux-mcp`). Claude
Desktop logs live in `~/Library/Logs/Claude/` (macOS) or `%APPDATA%\Claude\logs\`
(Windows); in Claude Code, `claude mcp get ameriflux` shows the connection status.

**`identityConfigured` is `false` although you set the variables.** They did not reach
the server process: desktop apps do not see variables exported in your shell. Put them in
the client's `env` block, or re-run the install script with `--with-identity`.

**Downloads report `auth_required` with `is_test_unset`.** `is_test` has no default on
purpose; set `AMERIFLUX_MCP_IDENTITY__IS_TEST` to `true` or `false` (see
[Download identity](identity.md#is_test)).

**Port already in use.** MCP over stdio uses no network port; a port error comes from an
HTTP deployment (`--transport http`, port 8080 by default) or something else on your
machine.

**Windows paths.** In JSON, write backslashes doubled (`C:\\Users\\…`) or use forward
slashes. Point at `ameriflux-mcp.exe`, not the extension-less name.

## Upgrading

```bash
# install script / from source
git pull origin main && uv sync
# uv tool
uv tool install --reinstall git+https://github.com/idss-mesa/ameriflux-mcp
```

Registrations made by the install script keep pointing at `.venv/bin/ameriflux-mcp`, so
`git pull && uv sync` is enough; restart desktop apps afterwards.

## Uninstallation

`--uninstall` leaves each edited file's `.bak` copy behind; if you used
`--with-identity`, those backups (owner-only, like the files) still contain your user
ID and email, so delete them too.

```bash
scripts/install.sh --uninstall       # remove the server from every agent config
cd .. && rm -rf ameriflux-mcp        # if installed from source
uv tool uninstall ameriflux-mcp      # if installed with uv tool
rm -rf ~/.cache/ameriflux-mcp        # the response cache (from build step 3)
```

Downloaded data in `~/ameriflux-downloads` is yours; remove it separately if you no
longer need it.

## Next steps

- [Quickstart](quickstart.md): a first session.
- [Download identity](identity.md): what downloads disclose and how to configure them.
- [Clients](clients.md): per-client configuration.
- [Configuration](configuration.md): every setting.

[^uv]: uv documentation. <https://docs.astral.sh/uv/>
[^uv-install]: Installing uv. <https://docs.astral.sh/uv/getting-started/installation/>
[^gh]: GitHub CLI. <https://cli.github.com/>
[^repo]: ameriflux-mcp source repository. <https://github.com/idss-mesa/ameriflux-mcp>

---8<--- https://idss-mesa.github.io/ameriflux-mcp/getting-started/quickstart/

---
title: "Quickstart"
description: "A first session with ameriflux-mcp: register it with Claude Code, check it with amf_ping, find a tower, check its data and get a citation."
type: Tutorial
tags:
  - getting-started
  - quickstart
  - tutorial
generated:
  by: "claude/opus-5.5"
  at: "2026-10-24T00:00:00Z"
sources:
  - id: claude-code-mcp
    resource: "https://docs.claude.com/en/docs/claude-code/mcp"
    title: "Claude Code — MCP"
    author: "team:anthropic"
  - id: amf-products
    resource: "https://ameriflux.lbl.gov/data/flux-data-products/"
    title: "AmeriFlux flux data products"
    author: "team:ameriflux"
  - id: design
    resource: "https://github.com/idss-mesa/ameriflux-mcp/blob/main/DESIGN.md"
    title: "ameriflux-mcp design (tool surface)"
    author: "team:idss-mesa"
status: draft
stale_after: "2027-04-23T00:00:00Z"
---

# Quickstart

This walks through a first session in Claude Code[^claude-code-mcp]; other clients work
the same way once connected ([Clients](clients.md)).

!!! note "Results abbreviated"

    The results below are shortened; the [tool reference](../tools/reference.md) lists
    every field, following the design[^design]. Step 6 needs downloads turned on
    (`AMERIFLUX_MCP_DOWNLOADS__ENABLED=true`; they are off by default) and a
    [download identity](identity.md) before `confirm=true` sends anything. The
    `plan_site_analysis` prompt runs the same sequence for chosen sites.

## 1. Register the server

```bash
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](identity.md).

## 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

```json
{"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

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

→ the published years per site and product[^amf-products]. `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

```json
{"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

```json
{"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](../tools/downloads.md)). Then
`amf_preview_data(site="US-Ha1", product="FLUXNET", resolution="DD")` summarizes the
daily file without loading it all.

## 7. Cite it

```json
{"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](../about/citing-ameriflux.md).

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

[^claude-code-mcp]: Claude Code — MCP. <https://docs.claude.com/en/docs/claude-code/mcp>
[^amf-products]: AmeriFlux flux data products. <https://ameriflux.lbl.gov/data/flux-data-products/>
[^design]: ameriflux-mcp design. <https://github.com/idss-mesa/ameriflux-mcp/blob/main/DESIGN.md>

---8<--- https://idss-mesa.github.io/ameriflux-mcp/getting-started/sync-cyverse/

---
title: "Sync downloads to CyVerse"
description: "Mirror the ameriflux-mcp download folder to the CyVerse Data Store with a GoCommands sync script that launchd (macOS) or cron (Linux) runs hourly."
type: Guide
tags:
  - getting-started
  - downloads
  - cyverse
  - gocommands
  - sync
generated:
  by: "claude/opus-5.5"
  at: "2026-10-24T00:00:00Z"
sources:
  - id: gocommands
    resource: "https://github.com/cyverse/gocommands"
    title: "GoCommands — iRODS command-line client"
    author: "team:cyverse"
  - id: cyverse-install
    resource: "https://learning.cyverse.org/ds/gocommands/installation/"
    title: "GoCommands Installation and Upgrade"
    author: "team:cyverse"
  - id: cyverse-config
    resource: "https://learning.cyverse.org/ds/gocommands/configuration/"
    title: "GoCommands Configuration"
    author: "team:cyverse"
  - id: apple-launchd
    resource: "https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html"
    title: "Creating Launch Daemons and Agents"
    author: "team:apple"
  - id: idss-mesa
    resource: "https://idss-mesa.github.io/docs/"
    title: "IDSS MESA documentation"
    author: "team:idss-mesa"
status: draft
stale_after: "2027-04-24T00:00:00Z"
---

# Sync downloads to CyVerse

[`amf_download_data`](../tools/downloads.md) writes AmeriFlux files into
`downloads.directory` (`~/ameriflux-downloads` by default) on the machine running the
server, one folder per product with a checksum sidecar beside each file. To keep that
folder mirrored in the CyVerse Data Store, for the Discovery Environment, for sharing
or as the home of a MESA project, pair it with GoCommands[^gocommands], CyVerse's
command-line client, and a short script that runs `gocmd sync` every hour.

!!! note "Adapted from neon-mcp"

    The script is neon-mcp's, which was tested with GoCommands v0.12.4 on macOS (Apple
    Silicon). This AmeriFlux variant changes the paths and adds the download-in-progress
    check. It has been dry-run on Linux with a stand-in for `gocmd` (the lock, the log
    and the `.part` skip work), but not yet against the Data Store, and the Linux
    `md5sum` check and cron line have not been run.

## What the sync does

* **One way, local → Data Store.** Your machine is the source. New and changed files
  upload; unchanged files are skipped by checksum, so a run with nothing new moves no
  data. `-k` verifies each upload's checksum.
* **It never deletes anything in the Data Store.** The script leaves out `--delete`,
  so files that exist only in the Data Store survive, such as the
  `.mesa/ducklake/` history of a MESA project. The flip side: deleting or renaming a
  file locally leaves the old copy in the Data Store until you remove it with
  `gocmd rm`.
* **Tags (AVUs) on a file survive when sync overwrites its content.** New files arrive
  with only the tags CyVerse adds itself (`ipc_UUID`, `ipc-filetype`). `gocmd sync`
  moves bytes, not metadata, and does not go through MESA, so it records no DuckLake
  history.
* **Hidden files upload too.** gocmd has no exclude option, so the script deletes
  macOS `.DS_Store` files before each run.
* **Never mid-download.** While `amf_download_data` is writing a `<name>.part` file the
  script skips the run, so a half-written file never reaches the Data Store; the next
  hourly run picks the finished file up.
* **Provenance travels with the data.** The `<name>.amf.json` sidecars (sha256, ETag,
  citation) and the `manifests/` folder upload too. They hold no user ID, email or
  description.

## 1. Install GoCommands

CyVerse publishes one-line installers per platform[^cyverse-install]. The steps below
do the same for the latest release, check the download against its published MD5 and
put `gocmd` in `~/.local/bin` (there is no Homebrew tap). Set `PLATFORM` to
`darwin-arm64`, `darwin-amd64`, `linux-amd64` or `linux-arm64`:

```bash
GOCMD_VER=$(curl -sL https://raw.githubusercontent.com/cyverse/gocommands/main/VERSION.txt)
PLATFORM=darwin-arm64
URL=https://github.com/cyverse/gocommands/releases/download/${GOCMD_VER}/gocmd-${GOCMD_VER}-${PLATFORM}.tar.gz
curl -sSL -o gocmd.tar.gz "$URL" && curl -sSL -o gocmd.tar.gz.md5 "$URL.md5"

case "$(uname -s)" in
  Darwin) SUM=$(md5 -q gocmd.tar.gz) ;;
  *) SUM=$(md5sum gocmd.tar.gz | cut -d' ' -f1) ;;
esac
[ "$SUM" = "$(cat gocmd.tar.gz.md5)" ] && echo "checksum OK"

mkdir -p ~/.local/bin && tar -xzf gocmd.tar.gz -C ~/.local/bin gocmd
~/.local/bin/gocmd --version
```

## 2. Log in once

Run `gocmd init` yourself, in your own terminal, and answer the prompts with your
CyVerse account[^cyverse-config]:

| Prompt | Value |
|---|---|
| `irods_host` | `data.cyverse.org` |
| `irods_port` | `1247` |
| `irods_zone_name` | `iplant` |
| `irods_user_name` | your CyVerse username |
| `irods_user_password` | your CyVerse password |

`init` writes its configuration under `~/.irods`, and every later `gocmd` call,
scheduled ones included, reuses it. Keep the password out of scripts, shell history
and command lines. Check the login with `gocmd ls`, then create the destination
collection:

```bash
~/.local/bin/gocmd mkdir -p /iplant/home/YOUR_USERNAME/ameriflux-downloads
```

## 3. Save the sync script

Save this as `~/.local/bin/ameriflux-sync`, set `SRC` and `DEST`, and make it
executable with `chmod 755 ~/.local/bin/ameriflux-sync`. Point `SRC` at one product
folder inside the download directory (for example `~/ameriflux-downloads/FLUXNET`) to
sync just those files, or at the download directory itself to mirror everything
ameriflux-mcp downloads. Point `DEST` at the matching Data Store collection.

```bash
#!/bin/bash
# ameriflux-sync: one-way upload of the local ameriflux-mcp download folder to the CyVerse
# Data Store with GoCommands. launchd (macOS) or cron (Linux) runs it every
# hour; run it by hand any time.
#
# Never add --delete: the iRODS copy holds files that exist only there
# (.mesa/ducklake history), and those must survive every run.
set -uo pipefail

SRC="$HOME/ameriflux-downloads"
DEST="/iplant/home/YOUR_USERNAME/ameriflux-downloads"
GOCMD="$HOME/.local/bin/gocmd"
STATE="$HOME/.local/state/ameriflux-sync"
case "$(uname -s)" in
  Darwin) LOG="$HOME/Library/Logs/ameriflux-sync.log" ;;
  *) LOG="$STATE/ameriflux-sync.log" ;;
esac
MAX_LOG_BYTES=1048576

mkdir -p "$STATE" "$(dirname "$LOG")"
if [ -f "$LOG" ] && [ "$(wc -c <"$LOG")" -gt "$MAX_LOG_BYTES" ]; then
  mv -f "$LOG" "$LOG.1"
fi
exec >>"$LOG" 2>&1

log() { printf '%s %s\n' "$(date '+%Y-%m-%dT%H:%M:%S%z')" "$*"; }

# One run at a time: a slow upload must not overlap the next hourly start.
LOCK="$STATE/lock"
if ! mkdir "$LOCK" 2>/dev/null; then
  if kill -0 "$(cat "$LOCK/pid" 2>/dev/null)" 2>/dev/null; then
    log "skip: previous run (pid $(cat "$LOCK/pid")) still active"
    exit 0
  fi
  log "removing stale lock"
  rm -rf "$LOCK"
  mkdir "$LOCK"
fi
echo $$ >"$LOCK/pid"
trap 'rm -rf "$LOCK"' EXIT

if [ ! -d "$SRC" ]; then
  log "error: $SRC does not exist"
  exit 1
fi

# A download in progress writes <name>.part; wait for the next run rather than upload it.
if [ -n "$(find "$SRC" -name '*.part' -type f -print -quit)" ]; then
  log "skip: a download is in progress"
  exit 0
fi

# gocmd has no exclude option, so remove Finder metadata before it can upload.
find "$SRC" -name .DS_Store -type f -print -delete | sed 's/^/deleted local /'

log "sync start $SRC -> i:$DEST"
# --no_root: sync the folder's contents into DEST, not into DEST/<name of SRC>.
# Unchanged files are skipped by checksum; drop those per-file notices.
"$GOCMD" sync -k --no_root "$SRC" "i:$DEST" 2>&1 |
  grep -v 'with the same hash already exists'
status=${PIPESTATUS[0]}
log "sync end status=$status"
exit "$status"
```

What the pieces do:

* `--no_root` puts the *contents* of `SRC` into `DEST`. Without it, gocmd creates a
  collection named after `SRC` inside `DEST`.
* The lock stops a slow upload from overlapping the next hourly start, and clears
  itself if a run was killed.
* The `.part` check skips a run while ameriflux-mcp is still writing a file.
* The log keeps one line at the start and end of each run plus anything gocmd
  reports; it rolls over to `ameriflux-sync.log.1` past 1 MB.

Run it once by hand before scheduling it:

```bash
~/.local/bin/ameriflux-sync; echo "exit=$?"
tail -3 ~/Library/Logs/ameriflux-sync.log     # Linux: ~/.local/state/ameriflux-sync/ameriflux-sync.log
```

## 4. Run it every hour

### macOS: launchd

Save this as `~/Library/LaunchAgents/local.ameriflux-sync.plist`[^apple-launchd], replacing
`YOUR_MAC_USER`: launchd does not expand `~` or `$HOME`, so the paths must be
absolute.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>Label</key>
	<string>local.ameriflux-sync</string>
	<key>ProgramArguments</key>
	<array>
		<string>/bin/bash</string>
		<string>/Users/YOUR_MAC_USER/.local/bin/ameriflux-sync</string>
	</array>
	<key>StartInterval</key>
	<integer>3600</integer>
	<key>RunAtLoad</key>
	<true/>
	<key>ProcessType</key>
	<string>Background</string>
	<key>LowPriorityIO</key>
	<true/>
	<key>StandardOutPath</key>
	<string>/Users/YOUR_MAC_USER/Library/Logs/ameriflux-sync.launchd.log</string>
	<key>StandardErrorPath</key>
	<string>/Users/YOUR_MAC_USER/Library/Logs/ameriflux-sync.launchd.log</string>
</dict>
</plist>
```

Load it. It runs straight away (`RunAtLoad`), then every hour, and loads again at
each login:

```bash
plutil -lint ~/Library/LaunchAgents/local.ameriflux-sync.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/local.ameriflux-sync.plist
```

macOS may show a "background item added" notice for `bash`; that is this job. After
editing the plist, `bootout` and `bootstrap` it again. To stop it:

```bash
launchctl bootout gui/$(id -u)/local.ameriflux-sync
rm ~/Library/LaunchAgents/local.ameriflux-sync.plist   # or it loads again at next login
```

### Linux: cron

Add one line with `crontab -e`:

```text
0 * * * * $HOME/.local/bin/ameriflux-sync
```

## Check on it

A failing sync is silent: if your CyVerse password changes or the network is down,
every run fails and nothing tells you. Look for a non-zero status now and then:

```bash
grep 'sync end status=[^0]' ~/Library/Logs/ameriflux-sync.log    # any failed runs
launchctl print gui/$(id -u)/local.ameriflux-sync | grep 'last exit code'   # macOS
```

A failed login is fixed by running `gocmd init` again.

## Syncing into a MESA project

If `DEST` is a MESA project, its `.mesa/ducklake/` history exists only in the Data
Store, which is why the script must never use `--delete`. The sync carries file
content only: to tag new files with DataCite or ontology metadata and record that in
the project's history, use mesa-mcp; see the
[IDSS MESA documentation](https://idss-mesa.github.io/docs/){target=_blank}[^idss-mesa].
Sync to a copy you own, and publish curated or shared copies deliberately rather
than syncing into them.

## Data policy

A shared collection passes the data on. Data under CC-BY-4.0 can be shared with
attribution; data under the AmeriFlux Legacy policy or FLUXNET2015 Tier Two come with
conditions on use and publication. Keep the synced copy private unless you know every
file's policy allows sharing: each sidecar records the policy it was downloaded under,
and `ameriflux://guide/data-policy` explains the obligations.

[^gocommands]: GoCommands — iRODS command-line client. <https://github.com/cyverse/gocommands>
[^cyverse-install]: GoCommands Installation and Upgrade. <https://learning.cyverse.org/ds/gocommands/installation/>
[^cyverse-config]: GoCommands Configuration. <https://learning.cyverse.org/ds/gocommands/configuration/>
[^apple-launchd]: Creating Launch Daemons and Agents. <https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html>
[^idss-mesa]: IDSS MESA documentation. <https://idss-mesa.github.io/docs/>

---8<--- https://idss-mesa.github.io/ameriflux-mcp/tools/citation/

---
title: "Citations and BADM"
description: "Cite AmeriFlux and FLUXNET2015 sites with amf_get_citation (versioned text, policy obligations, acknowledgments) and read site metadata with amf_get_badm."
type: Guide
tags:
  - tools
  - citation
  - data-policy
  - badm
generated:
  by: "claude/opus-5.5"
  at: "2026-10-24T00:00:00Z"
sources:
  - id: research
    resource: "https://github.com/idss-mesa/ameriflux-mcp/blob/main/RESEARCH.md"
    title: "ameriflux-mcp verified research (sections 4 and 8)"
    author: "team:idss-mesa"
  - id: design
    resource: "https://github.com/idss-mesa/ameriflux-mcp/blob/main/DESIGN.md"
    title: "ameriflux-mcp design (D9, D10, D35)"
    author: "team:idss-mesa"
  - id: amf-policy
    resource: "https://ameriflux.lbl.gov/data/data-policy/"
    title: "AmeriFlux Data Policy"
    author: "team:ameriflux"
  - id: fluxnet-policy
    resource: "https://fluxnet.org/data/data-policy/"
    title: "FLUXNET Data Policy"
    author: "team:fluxnet"
status: stable
stale_after: "2027-04-24T00:00:00Z"
---

# Citations and BADM

`amf_get_citation` gathers everything you need to credit a set of sites, and
`amf_get_badm` returns the site metadata the API exposes. Both work over stdio and HTTP
without an account. [Citing AmeriFlux and FLUXNET data](../about/citing-ameriflux.md)
explains the policies behind them.

## amf_get_citation

Give up to 50 sites and one product:

| `product` | Citation |
| --- | --- |
| `BASE-BADM` (default) | AmeriFlux's own text for the site's BASE DOI, with the version (`Ver. 28-5`) |
| `BIF` (BADM) | The BASE-BADM citation: BADM has no DOI of its own |
| `FLUXNET` (FLUXNET-1F) | AmeriFlux's text for the FLUXNET DOI (`Ver. v1.3_r1 (1991-2025)`) |
| `FLUXNET2015` | Built from the DOI record the way the FLUXNET DOI page shows it: authors, Tier Two years, title, "Dataset", DOI |

FLUXNET-CH4 citations come in v0.2 (`feature_unavailable` until then).

The result has:

- **`citations`**: one per site, cited as written in the reference list (not in
  supplementary material). `source` says where the text came from: `amfcdn` (AmeriFlux),
  `constructed` (FLUXNET2015) or `datacite` (a fallback when the AmeriFlux DOI service is
  down; it has no version and comes with a `versionMissing` warning). Set
  `include_bibtex` for a BibTeX entry per site.
- **`missing`**: requested sites without a citation and why (a Legacy site has no FLUXNET
  product; US-xSR is not part of FLUXNET2015).
- **`effectivePolicy`**: the policy the whole selection must follow, with each obligation
  marked `required` or `recommended`[^design]. Mixing CC-BY and Legacy sites means Legacy;
  any Tier Two site makes FLUXNET2015 Tier Two.
- **`acknowledgments`**: verbatim text from the policy page[^amf-policy]. Legacy data name
  the data *portal*, CC-BY data the data *service*, and FLUXNET adds the networks and ERA5
  text.
- **`siteFunding`**: under Legacy, each site's sponsors from its DOI record, to
  acknowledge. When a record has none, a note points to the site's BADM.
- **`dataAvailability`**: the sentence for a Data Availability section, with the product
  filled in and the AmeriFlux-listed `[SOURCE]` options.
- **`processingReferences`**: Chu et al. 2023 (BASE) or Pastorello et al. 2020 (FLUXNET,
  FLUXNET2015).

```json
{"tool": "amf_get_citation", "arguments": {"sites": ["US-Ha1", "CA-Let"]}}
{"tool": "amf_get_citation", "arguments": {"sites": ["US-Ha1", "RU-Sam"], "product": "FLUXNET2015"}}
```

The first call returns the Legacy policy, because CA-Let shares its data under it; the
second returns Tier Two, because RU-Sam is Tier Two only[^research].

## amf_get_badm

BADM (Biological, Ancillary, Disturbance and Metadata) for one site, grouped as the API
exposes it:

| Section | Content |
| --- | --- |
| `site` | Location (GRP_LOCATION), IGBP and climate with AmeriFlux's descriptions, tower dates, site URL, description |
| `team` | Names, roles and institutions; emails only under the two-flag rule ([Configuration](../getting-started/configuration.md)) |
| `disturbance` | Dominant disturbance and management, and the flux gas species measured |
| `funding` | Sponsor and contributor organizations from the DOI record: what a Legacy site asks you to acknowledge |
| `references` | The site's reference papers, paged (`references_limit`, `references_offset`) |
| `instruments` | Variables with height (m; negative is depth), instrument models and dates, from the measurement-height file; `variables` narrows them by base name (`TA`) or exact column (`SWC_1_1_1`) |

The complete BADM, with every group and its dates, is the BIF file inside each BASE-BADM
download.

```json
{"tool": "amf_get_badm", "arguments": {"site": "US-Ha1", "include": ["funding", "instruments"], "variables": ["TA"]}}
```

## Resources

| URI | Content |
| --- | --- |
| `ameriflux://guide/data-policy` | CC-BY-4.0 and Legacy, Tier One and Tier Two, and why mixing escalates |
| `ameriflux://reference/acknowledgments` | The verbatim texts, with the date they were checked against the policy pages[^fluxnet-policy] |

[^research]: ameriflux-mcp verified research. <https://github.com/idss-mesa/ameriflux-mcp/blob/main/RESEARCH.md>
[^design]: ameriflux-mcp design. <https://github.com/idss-mesa/ameriflux-mcp/blob/main/DESIGN.md>
[^amf-policy]: AmeriFlux Data Policy. <https://ameriflux.lbl.gov/data/data-policy/>
[^fluxnet-policy]: FLUXNET Data Policy. <https://fluxnet.org/data/data-policy/>

---8<--- https://idss-mesa.github.io/ameriflux-mcp/tools/discovery/

---
title: "Discovery and availability"
description: "Find flux tower sites with amf_search_sites, read one with amf_get_site, and check which years exist per product and policy with amf_get_availability."
type: Guide
tags:
  - tools
  - discovery
  - availability
  - data-policy
generated:
  by: "claude/opus-5.5"
  at: "2026-10-24T00:00:00Z"
sources:
  - id: research
    resource: "https://github.com/idss-mesa/ameriflux-mcp/blob/main/RESEARCH.md"
    title: "ameriflux-mcp verified research (sections 1 and 3)"
    author: "team:idss-mesa"
  - id: design
    resource: "https://github.com/idss-mesa/ameriflux-mcp/blob/main/DESIGN.md"
    title: "ameriflux-mcp design (D6, D7, D10, D20, D34)"
    author: "team:idss-mesa"
  - id: amf-sites
    resource: "https://ameriflux.lbl.gov/sites/site-search/"
    title: "AmeriFlux site search"
    author: "team:ameriflux"
status: stable
stale_after: "2027-04-24T00:00:00Z"
---

# Discovery and availability

Three tools answer "which towers, and what data do they have?" They read the AmeriFlux
site catalog and availability lists, which need no account, and work over stdio and
HTTP alike. Inputs and result fields are in the [Tool reference](reference.md).

## One catalog for three collections

ameriflux-mcp merges three lists into one catalog[^research], the same data the
[AmeriFlux site search](https://ameriflux.lbl.gov/sites/site-search/){target=_blank}[^amf-sites]
shows:

| Collection | Sites | What it is |
| --- | --- | --- |
| `ameriflux` | about 856 | AmeriFlux sites across the Americas, with BASE and FLUXNET (FLUXNET-1F) years, data policy, DOIs, team, networks and measured variables |
| `fluxnet2015` | 212 | The frozen FLUXNET2015 release, worldwide, with Tier One (CC-BY-4.0) and Tier Two year ranges |
| `fluxnet_ch4` | 81 | The FLUXNET-CH4 Community Product V1.0 |

A tower in several lists is one site (US-Ha1 is in `ameriflux` and `fluxnet2015`). Sites
only in a FLUXNET list, such as DE-Tha, carry the sparser FLUXNET fields. The catalog is
cached for six hours, and on stdio also on disk, so a restarted server does not reload
it[^design].

## Naming a site

Every `site` or `sites` argument accepts:

- a site ID in any case: `US-Ha1`, `us-ha1`;
- a NEON site code: `SRER` is `US-xSR`;
- a FLUXNET2015 ID renamed after the release: `DK-ZaF` is `GL-ZaF` (with a note);
- a site name: `Santa Rita`, `Mayberry Wetland`.

Each interpretation is echoed in `resolved`. A name that fits several sites fails with
`ambiguous_input` and lists them (`Harvard Forest` gives US-Ha1, US-Ha2, US-Ha3, …): pick
one and call again.

## amf_search_sites

Filters combine (every filter must hold): words in the ID, name, place, NEON code or
networks (prefixes count: `harv`); `collection`; `product` and `policy`; IGBP class;
Köppen climate (prefixes: `B` is every dry climate); country (code as in site IDs, or
name); state or province; tower status; member network (`NEON`, `LTER`, `Phenocam`, …);
a bounding box or `near` a point; data years overlapping a window, or at least
`min_years`; measured BASE variables (`FCH4`); flux gas species (`CH4`).

Each site comes with its years per product, its policy and its member networks;
`facets` count every match by collection, IGBP, country, policy and status, so you can
see the shape of a large result before paging through it.

```json
{"tool": "amf_search_sites", "arguments": {"network": ["NEON"], "igbp": ["GRA"]}}
{"tool": "amf_search_sites", "arguments": {"near": {"latitude": 34.36, "longitude": -106.7, "radius_km": 60}}}
{"tool": "amf_search_sites", "arguments": {"collection": "fluxnet2015", "policy": "TIER2"}}
```

## amf_get_site

One site, with the ecosystem and climate described in AmeriFlux's own words (from the
[vocabularies](#resources)), the policy and what it asks of you, DOIs, years per
product, team (names, roles, institutions), measured BASE variables and links to other
networks:

- **NEON**: for NEON towers, the NEON site code and NEON's own flux product,
  DP4.00200.001, with a next step for the NEON MCP server.
- **LTER**: for sites in the [LTER crosswalk](#resources), the LTER site and its EDI
  scope, with a next step for the EDI MCP server. The crosswalk is curated and marked
  draft; each link says whether it comes from the upstream LTER tag or the site name.

Team emails are withheld unless you ask for contacts **and** the server's operator
enabled `privacy.allow_contact_emails` ([Configuration](../getting-started/configuration.md)).

!!! note "AmeriFlux's Köppen wording"

    AmeriFlux describes `Bsh` as "Steppe: very cold winter" and `Bsk` as "Steppe: warm
    winter", the reverse of standard Köppen-Geiger (BSh hot, BSk cold semi-arid). The
    text is passed on as AmeriFlux shows it, with a `koeppenNote` flagging the swap.

## amf_get_availability

The years each site has per product, from AmeriFlux's availability lists:

| Product | Policies | Rows |
| --- | --- | --- |
| `BASE-BADM` | CCBY4.0, LEGACY | years |
| `FLUXNET` (FLUXNET-1F) | CCBY4.0 only | years |
| `FLUXNET2015` | CCBY4.0, TIER2 | years |
| `FLUXNET-CH4` | CCBY4.0, TIER2 | years |
| `BIF` (BADM) | CCBY4.0, LEGACY | membership only: AmeriFlux publishes no BADM years |

Without a `policy`, every row is labelled with the policy its data are actually shared
under. LEGACY and TIER2 lists are supersets of the CC-BY lists (a CC-BY site may also
be used under the stricter terms), so asking for `policy="LEGACY"` returns every site,
while the default labels US-Ha1 `CCBY4.0` and CA-Let `LEGACY`.

For the sites you name, the result also lists:

- **`emptySites`**: requested sites without data for a product, and why (a Legacy site
  has no FLUXNET product; RU-Sam has no Tier One years; no data in your year window);
- **`policyVerdict`**: the policy the selection must follow per product, with its
  obligations: mixing CC-BY and Legacy sites means Legacy, mixing tiers means Tier Two;
- **`combinedObligations`**: every obligation once, across collections.

An impossible product and policy pair (FLUXNET under LEGACY, BASE-BADM under TIER2)
fails with `invalid_argument` before any request: the AmeriFlux API would answer it
with empty rows rather than an error.

## Resources

| URI | Content |
| --- | --- |
| `ameriflux://site/{site_id}` | One site's card (the `amf_get_site` result) |
| `ameriflux://reference/vocabularies` | IGBP classes and Köppen climates in AmeriFlux's wording, the product × policy matrix, intended-use codes, member networks |
| `ameriflux://reference/neon-crosswalk` | NEON site codes and their AmeriFlux sites, from the live catalog |
| `ameriflux://reference/lter-crosswalk` | AmeriFlux sites linked to LTER sites and EDI scopes (draft) |

[^research]: ameriflux-mcp verified research. <https://github.com/idss-mesa/ameriflux-mcp/blob/main/RESEARCH.md>
[^design]: ameriflux-mcp design. <https://github.com/idss-mesa/ameriflux-mcp/blob/main/DESIGN.md>
[^amf-sites]: AmeriFlux site search. <https://ameriflux.lbl.gov/sites/site-search/>

---8<--- https://idss-mesa.github.io/ameriflux-mcp/tools/downloads/

---
title: "Downloads"
description: "Download AmeriFlux BASE-BADM, FLUXNET and bulk BADM with amf_download_data: a plan first, consent with confirm=true, verified files and sidecars."
type: Guide
tags:
  - tools
  - downloads
  - identity
  - data-policy
generated:
  by: "claude/opus-5.5"
  at: "2026-10-24T00:00:00Z"
sources:
  - id: amf-policy
    resource: "https://ameriflux.lbl.gov/data/data-policy/"
    title: "AmeriFlux Data Policy"
    author: "team:ameriflux"
  - id: research
    resource: "https://github.com/idss-mesa/ameriflux-mcp/blob/main/RESEARCH.md"
    title: "ameriflux-mcp verified research (section 5, downloads)"
    author: "team:idss-mesa"
  - id: design
    resource: "https://github.com/idss-mesa/ameriflux-mcp/blob/main/DESIGN.md"
    title: "ameriflux-mcp design (D11-D18, D37)"
    author: "team:idss-mesa"
status: draft
stale_after: "2027-01-24T00:00:00Z"
---

# Downloads

`amf_download_data` downloads AmeriFlux data through the route the AmeriFlux website
uses: one request that tells the site PIs who is downloading and why[^amf-policy]. It
runs only over **stdio** and needs a [download identity](../getting-started/identity.md).
Inputs and result fields are in the [Tool reference](reference.md).

!!! warning "Off by default"

    Downloads are **off by default** until AmeriFlux confirms that third-party clients may use its download request (question Q1 in the project's [support questions](https://github.com/idss-mesa/ameriflux-mcp/blob/main/research/questions.md){target=_blank}). Until then the tool is not listed. To use it anyway, set
    `AMERIFLUX_MCP_DOWNLOADS__ENABLED=true` in the server's environment (or start it
    with `--downloads`); `amf_ping` reports `downloadsEnabled`.

| Product | `sites` | What arrives |
| --- | --- | --- |
| `BASE-BADM` (default) | up to 20 sites | `AMF_<SITE>_BASE-BADM_<ver>.zip`: the BASE CSV and the site's BIF |
| `FLUXNET` | up to 20 CC-BY-4.0 sites | `AMF_<SITE>_FLUXNET_<years>_v1.3_r1.zip` (FULLSET) |
| `BIF` | `AA-Flx` (sites with data) or `AA-Net` (all sites) | the bulk BADM workbook |

FLUXNET2015 and FLUXNET-CH4 files come from fluxnet.org's login-protected form, which
ameriflux-mcp does not automate (`feature_unavailable`; see
`ameriflux://guide/fluxnet2015-access`).

## 1. The plan

Without `confirm`, the tool returns a plan and sends nothing:

```json
{"tool": "amf_download_data", "arguments": {"sites": ["AR-Bal", "CA-Let"], "product": "FLUXNET"}}
```

- `disclosure`: the request AmeriFlux would receive. The user ID, email and name show as
  `configured (not shown)`; the intended-use category and the description appear in
  full, with ` [ameriflux-mcp]` appended, because that is what the PIs read. `recipients`
  says who receives it: the PIs of each site and the AmeriFlux Data Download Log.
- `eligible` and `ineligible`: here CA-Let is ineligible, because it shares its data
  under the Legacy policy and the FLUXNET product is CC-BY-4.0 only.
- `policy`: the policy code to accept (`CCBY4.0` or `LEGACY`), why, and its
  obligations. For BASE-BADM, one Legacy site makes the whole request Legacy, unless you
  ask for `policy='CCBY4.0'`, which leaves the Legacy sites out.
- `blockers` and `ready`: what must be configured first (the identity, a complete
  profile, `is_test`).
- `localCopies`: matching files already in the download directory. A new request still
  notifies the PIs, so read those first if they are current.

## 2. Consent

The agent shows the user the plan. Only if they agree does it call again with
`confirm=true` and `accept_data_policy` set to the plan's policy:

```json
{"tool": "amf_download_data", "arguments": {"sites": ["AR-Bal"], "product": "FLUXNET", "accept_data_policy": "CCBY4.0", "confirm": true}}
```

The checks run in this order, and each fails before anything is sent: the product and
policy combination, then the accepted policy (`policy_not_accepted`,
`policy_mismatch`), then the identity (`auth_required` with `identity_missing`,
`profile_missing`, `profile_incomplete` or `is_test_unset`), then at least one eligible
site.

!!! warning "Each confirmed call is a new request"

    Every `confirm=true` call sends one request, and AmeriFlux notifies the PIs again,
    so the tool is marked not idempotent[^design]. A file already on disk is kept rather than
    fetched twice, but the request is still logged.

## 3. The transfer

AmeriFlux answers with links to static files on `ftp.fluxdata.org`[^research]. The
server:

1. keeps only links on its allow-list (`/.ameriflux_downloads/`), with a plain file name,
   for a requested site; `FLUXNET-BIF` links are skipped, as amerifluxr does. Each skipped
   link is listed in `skipped` with the reason;
2. strips the `?=<user_id>` tag from each link, so the file server never receives the
   identity. The file is the same with or without it;
3. sends a HEAD for the size and ETag, and checks `downloads.max_file_bytes` (1 GiB),
   `downloads.max_bytes_per_call` (2 GiB), `downloads.max_files_per_call` and the free
   disk space;
4. streams the file to `<name>.part` with `If-Match`, then checks that the ETag, the
   Content-Length and the byte count match the HEAD, and that every zip member passes
   its CRC;
5. moves it to `<downloads.directory>/<product>/<name>` and writes `<name>.amf.json`
   beside it.

A file that fails any check is not kept (`status: failed`, `checksum_mismatch`) and no
`.part` file is left behind. With `if_exists='skip'` (the default) an existing file is
kept, and `identical` says whether it matches the server copy; `if_exists='replace'`
fetches it again unless it is identical.

## What is written

```text
~/ameriflux-downloads/
  FLUXNET/AMF_AR-Bal_FLUXNET_2012-2013_v1.3_r1.zip
  FLUXNET/AMF_AR-Bal_FLUXNET_2012-2013_v1.3_r1.zip.amf.json
  manifests/amf_download_20261024T120000Z_FLUXNET.json
```

| File | Holds |
| --- | --- |
| `<name>.amf.json` | sha256, bytes, ETag, Last-Modified, the link without its tag, site, product, policy, version, download time, `isTest`, the site's citation and the policy obligations |
| `manifests/…json` | the request (sites, product, policy, profile name, intended-use category, `isTest`), each file's outcome, skipped links, AmeriFlux's manifest rows and the citations |

Neither file holds the user ID, email, name or description. AmeriFlux also returns the
PIs' contact emails: the result reports how many (`piContactCount`), and the emails are
never stored or shown.

## After the download

`amf_preview_data(file=…)` reads the zip in place, `amf_read_bif(file=…)` reads the
site's BADM, and `amf_get_citation` gives the citations and obligations for the
reference list. See [Local files](local-files.md). To mirror the download folder to the
CyVerse Data Store, see [Sync downloads to CyVerse](../getting-started/sync-cyverse.md).

[^amf-policy]: AmeriFlux Data Policy. <https://ameriflux.lbl.gov/data/data-policy/>
[^research]: ameriflux-mcp verified research. <https://github.com/idss-mesa/ameriflux-mcp/blob/main/RESEARCH.md>
[^design]: ameriflux-mcp design. <https://github.com/idss-mesa/ameriflux-mcp/blob/main/DESIGN.md>

---8<--- https://idss-mesa.github.io/ameriflux-mcp/tools/local-files/

---
title: "Local files"
description: "Find, preview and read AmeriFlux and FLUXNET files on your computer with amf_list_files, amf_preview_data and amf_read_bif, inside their zips and offline."
type: Guide
tags:
  - tools
  - local-files
  - fluxnet
  - badm
generated:
  by: "claude/opus-5.5"
  at: "2026-10-24T00:00:00Z"
sources:
  - id: research
    resource: "https://github.com/idss-mesa/ameriflux-mcp/blob/main/RESEARCH.md"
    title: "ameriflux-mcp verified research (section 6)"
    author: "team:idss-mesa"
  - id: design
    resource: "https://github.com/idss-mesa/ameriflux-mcp/blob/main/DESIGN.md"
    title: "ameriflux-mcp design (D23, D36)"
    author: "team:idss-mesa"
  - id: oneflux-readme
    resource: "https://github.com/fluxnet/ONEFlux/blob/main/oneflux/metadata/fluxnet_data_docs/README.txt"
    title: "ONEFlux FLUXNET data product README"
    author: "team:fluxnet"
status: stable
stale_after: "2027-04-24T00:00:00Z"
---

# Local files

Three tools read the AmeriFlux and FLUXNET files already on your computer. They run only
over **stdio** (a hosted server has no access to your disk), never use the network, and
read archives **in place**: nothing is extracted. Inputs and result fields are in the
[Tool reference](reference.md).

## Where they look

Files are readable only inside the **download directory** (`downloads.directory`,
default `~/ameriflux-downloads`) and any folder in **`local.roots`**
([Configuration](../getting-started/configuration.md)):

```bash
export AMERIFLUX_MCP_LOCAL__ROOTS=~/fluxnet2015,~/flux-archive
```

Paths are relative to a root (or absolute inside one). `archive.zip::member.csv` names
a member. A path that leaves the roots, including through a symbolic link, fails with
`invalid_argument` (`outside_local_roots`). FLUXNET2015 zips need a fluxnet.org account,
so you download them yourself and add their folder to `local.roots`; the server never
automates that login.

## amf_list_files

Lists every file whose name AmeriFlux or FLUXNET gave it, and classifies each archive
member[^research]:

| Family | Files |
| --- | --- |
| `base` | `AMF_<SITE>_BASE-BADM_<X-Y>.zip` holding `AMF_<SITE>_BASE_(HH\|HR)_<X-Y>.csv` and the site's BIF workbook |
| `bif` | `AMF_<SITE>_BIF_<date>.xlsx`, and the bulk `AA-Flx`/`AA-Net` files |
| `fluxnet` | AmeriFlux FLUXNET (ONEFlux v1.3) zips: FLUXMET, ERA5 and BIFVARINFO files per resolution, a BIF CSV, README and licence[^oneflux-readme] |
| `fluxnet2015` | FULLSET and SUBSET zips: data per resolution, ERAI, AUXMETEO and AUXNEE |
| `fluxnet_ch4` | Listed; reading arrives in v0.2 |

Each entry gives the site, resolution, years and version; members that cannot be read
say why (see [Safety](#safety)). Filter by `family` or `site`, or give a folder or a
single archive as `path`.

## amf_preview_data

Reads one CSV, by `file` or by `site` and `product` (the newest local version), and by
default the half-hourly or hourly member of an archive (`resolution` picks another).

- **Summary** (default): per column the count, missing values (`-9999`), min, max, mean,
  units at the file's resolution, and `outOfRange`: values beyond the FP Standard range
  ±5%, counted but kept. The file info gives the time step read from the timestamps,
  the time range, the `#` header lines of BASE files, and the site's UTC offsets.
- **Rows** (`mode='rows'`): a page of rows (`max_rows`, `offset`) within `start`/`end`.
  `to_utc=true` adds UTC timestamps, applying the offset in force on each row's date.
- **QC**: `qc_max` keeps HH/HR values whose `_QC` flag is at most the threshold (0
  measured … 3 poor); `qc_min_fraction` keeps DD and coarser values whose QC fraction
  is at least the threshold. Rejected values become null and are counted in
  `qcFiltered`.
- **SUBSET view**: `view='subset'` keeps only the FLUXNET2015 SUBSET variables of an
  AmeriFlux FLUXNET file.
- **Aux tables**: AUXMETEO and AUXNEE are read as plain tables, with text values
  listed.

```json
{"tool": "amf_preview_data", "arguments": {"site": "US-Ha1", "product": "FLUXNET", "resolution": "DD", "columns": ["NEE_VUT_REF", "GPP_NT_VUT_REF"], "qc_min_fraction": 0.8}}
{"tool": "amf_preview_data", "arguments": {"file": "AMF_US-Ha1_BASE-BADM_28-5.zip", "mode": "rows", "start": "2020-07-01", "end": "2020-07-02", "to_utc": true}}
```

!!! note "HH can mean hourly"

    ONEFlux v1.3 names its finest resolution `HH` even for hourly sites; the preview
    reads the step from `TIMESTAMP_START`/`TIMESTAMP_END` and says so when they differ.

A scan stops after `end`, or once it has read 256 MiB or run for 20 s
(`truncatedReason: budget`). Half-hourly BASE files reach hundreds of megabytes, so for
long records start with the DD or MM file, or narrow `start`, `end` and `columns`.

## amf_read_bif

Reads BADM Interchange Format files: the BIF workbook of a BASE-BADM zip, the BIF CSV of
a FLUXNET zip, or a BIF file on its own. It returns entries by group (filter with
`groups`, and with `site_id` in bulk files), the UTC offsets with their start dates, the
DOI and citation recorded for that version, and the funding acknowledgments.

**Personal data is withheld by default**: emails, postal and shipping addresses, and the
names of private land owners. They are shown only when you pass `include_contacts` and
the operator enabled `privacy.allow_contact_emails`. The citation in a BIF is the one of
that file's version; `amf_get_citation` gives the current one.

## Safety

Archives are read in place through a checker that refuses members with absolute or
`..` paths, symbolic links, encrypted members, members over 1 GiB uncompressed, and
members over 1 MiB that compress more than 200:1 (zip bombs)[^design]. Reads also stop if
a member decompresses past its declared size.

## Resources

| URI | Content |
| --- | --- |
| `ameriflux://guide/file-formats` | File names, CSV conventions, BIF and previews, for agents |
| `ameriflux://guide/fluxnet2015-access` | Getting FLUXNET2015 zips yourself and reading them here |

[^research]: ameriflux-mcp verified research. <https://github.com/idss-mesa/ameriflux-mcp/blob/main/RESEARCH.md>
[^design]: ameriflux-mcp design. <https://github.com/idss-mesa/ameriflux-mcp/blob/main/DESIGN.md>
[^oneflux-readme]: ONEFlux FLUXNET data product README. <https://github.com/fluxnet/ONEFlux/blob/main/oneflux/metadata/fluxnet_data_docs/README.txt>

---8<--- https://idss-mesa.github.io/ameriflux-mcp/tools/prompts-and-resources/

---
title: "Prompts, resources and status"
description: "The three ameriflux-mcp prompts, the guide and reference resources agents read, the site card template, and the amf_ping status report."
type: Guide
tags:
  - tools
  - prompts
  - resources
  - agents
generated:
  by: "claude/opus-5.5"
  at: "2026-10-24T00:00:00Z"
sources:
  - id: mcp-prompts
    resource: "https://modelcontextprotocol.io/specification/2026-07-28/server/prompts"
    title: "MCP specification: prompts"
    author: "team:modelcontextprotocol"
  - id: design
    resource: "https://github.com/idss-mesa/ameriflux-mcp/blob/main/DESIGN.md"
    title: "ameriflux-mcp design"
    author: "team:idss-mesa"
status: draft
stale_after: "2027-04-24T00:00:00Z"
---

# Prompts, resources and status

Besides its tools, ameriflux-mcp offers **prompts** (task recipes a client can show as
commands[^mcp-prompts]) and **resources** (guides and reference tables an agent reads on
demand). Both work over stdio and HTTP and need no account.

## Prompts

| Prompt | Arguments | What it asks the agent to do |
| --- | --- | --- |
| `find_flux_sites` | `question` (required), `region`, `ecosystem`, `years`, `variables` | Search towers with the filters the question implies, read the best candidates, check their years and policy, and end with a table. It downloads nothing. |
| `plan_site_analysis` | `sites` (required, up to 20), `product`, `variables`, `years` | Availability, variable meanings and BADM; then local files first, or a download **plan** shown to the user, confirmed only after they agree; a preview; citations. For FLUXNET2015 it explains the fluxnet.org route instead. |
| `cite_flux_data` | `sites` (required, up to 50), `product` | Every citation as returned, the acknowledgments verbatim, Legacy site funding, the data-availability sentence, the processing references and the obligations. |

Arguments are checked before a recipe is returned: site lists are capped, products are
normalized (`FLUXNET-1F` → `FLUXNET`), and years must read as `2012` or `2010-2015`. A
recipe names only tools and resources the server has.

## Guides

| URI | Read it for |
| --- | --- |
| `ameriflux://guide/agent-workflow` | The seven-call path from a question to previewed, cited data; inputs and errors |
| `ameriflux://guide/products` | BASE-BADM, BIF, FLUXNET, FLUXNET2015 and FLUXNET-CH4: which to use, FULLSET vs SUBSET, bulk BADM, versions |
| `ameriflux://guide/data-policy` | CC-BY-4.0, Legacy, Tier One and Tier Two, and why mixing escalates |
| `ameriflux://guide/variable-grammar` | How BASE and FLUXNET variable names are built |
| `ameriflux://guide/identity` | What a download discloses, how the user configures it, the download flow |
| `ameriflux://guide/file-formats` | File names and contents, timestamps, UTC offsets, previews, safety rules |
| `ameriflux://guide/fluxnet2015-access` | Getting FLUXNET2015 zips from fluxnet.org yourself |

## Reference tables

| URI | Content |
| --- | --- |
| `ameriflux://reference/vocabularies` | IGBP classes and Köppen climates in AmeriFlux's wording, the product × policy matrix, intended-use codes, networks |
| `ameriflux://reference/fp-variables` | The FP Standard variables with units and QA/QC ranges (live, or the bundled snapshot) |
| `ameriflux://reference/fluxnet-variables` | FLUXNET FULLSET/SUBSET and ONEFlux variables with units per resolution |
| `ameriflux://reference/acknowledgments` | The verbatim acknowledgment and data-availability texts, with the date checked |
| `ameriflux://reference/neon-crosswalk` | NEON site codes and their AmeriFlux IDs, from the live catalog |
| `ameriflux://reference/lter-crosswalk` | AmeriFlux sites linked to LTER sites and EDI scopes (draft) |

The template `ameriflux://site/{site_id}` returns one site's card, the same payload as
`amf_get_site`; NEON codes and FLUXNET2015 old IDs resolve too.

## amf_ping

`amf_ping` reports the server version, the protocol (`2026-07-28`) and transport, which
download-identity fields are configured (booleans and profile names only, never values),
whether downloads are enabled and where they go, the local roots, cache statistics and,
with `check_api=true`, whether one small AmeriFlux API request answers and how fast. Call
it first when a tool is missing or a download refuses. `ameriflux-mcp --check` runs the
same report offline from the command line.

[^mcp-prompts]: MCP specification: prompts. <https://modelcontextprotocol.io/specification/2026-07-28/server/prompts>

---8<--- https://idss-mesa.github.io/ameriflux-mcp/tools/reference/

---
title: "Tool reference"
description: "Every ameriflux-mcp tool with its inputs, result fields, upstream endpoints and annotations, generated from the tool registry."
type: MCP Tool Reference
tags:
  - tools
  - reference
  - generated
generated:
  by: "process:gen_tools_reference"
  at: "2026-10-25T00:00:00Z"
sources:
  - id: registry
    resource: "https://github.com/idss-mesa/ameriflux-mcp/tree/main/src/ameriflux_mcp/tools"
    title: "ameriflux-mcp tool registry"
    author: "team:idss-mesa"
status: stable
---

# Tool reference

Generated from the tool registry by `scripts/gen_tools_reference.py`; do not edit by hand. 12 tools are registered; `amf_download_data`, `amf_list_files`, `amf_preview_data`, `amf_read_bif` are offered only over stdio. Inputs are snake_case and outputs camelCase. Every result also carries `resolved`, `notes`, `nextSteps` and `source` (whose `backend` says what answered: the AmeriFlux API, its file server, or nothing upstream), and failures return `structuredContent.error` with a stable `code`. Tools still to come are on the [roadmap](roadmap.md).

| Tool | Title | Family | Download identity |
| --- | --- | --- | --- |
| [`amf_describe_variables`](#amf_describe_variables) | Describe variable names: grammar, units, QC and sites | [variables](variables.md) | no |
| [`amf_download_data`](#amf_download_data) | Download AmeriFlux data (with consent) | [data](downloads.md) | required |
| [`amf_get_availability`](#amf_get_availability) | Get data availability per site and product | [availability](discovery.md) | no |
| [`amf_get_badm`](#amf_get_badm) | Get a site's BADM metadata | [metadata](citation.md) | no |
| [`amf_get_citation`](#amf_get_citation) | Get citations and acknowledgments for sites | [citation](citation.md) | no |
| [`amf_get_site`](#amf_get_site) | Get one AmeriFlux or FLUXNET site | [discovery](discovery.md) | no |
| [`amf_list_files`](#amf_list_files) | List local AmeriFlux and FLUXNET files | [local](local-files.md) | no |
| [`amf_ping`](#amf_ping) | Check ameriflux-mcp status | [core](prompts-and-resources.md) | no |
| [`amf_preview_data`](#amf_preview_data) | Preview a local AmeriFlux or FLUXNET data file | [local](local-files.md) | no |
| [`amf_read_bif`](#amf_read_bif) | Read a local BADM (BIF) file | [local](local-files.md) | no |
| [`amf_search_sites`](#amf_search_sites) | Search AmeriFlux and FLUXNET sites | [discovery](discovery.md) | no |
| [`amf_search_variables`](#amf_search_variables) | Search the FP Standard and FLUXNET variable dictionaries | [variables](variables.md) | no |

## amf_describe_variables

**Describe variable names: grammar, units, QC and sites.** 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.

| | |
| --- | --- |
| Surface | `variables` |
| Download identity | not needed |
| Transports | http, stdio |
| Annotations | readOnly=true, destructive=false, idempotent=true, openWorld=true |
| Upstream endpoints | `GET amfcdn.lbl.gov/api/v1/fp_var` |

**Inputs**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `names` | array of string | yes |  | Variable names as in file headers: TA_F_1_1_1, FC_PI_F_1_1_A, GPP_NT_VUT_REF, NEE_VUT_05, TS_F_MDS_2_QC … (min items 1; max items 20) |
| `resolution` | string \\| null |  | null | HH (also HR), DD, WW, MM or YY: units and QC meaning at this resolution (FLUXNET). Default: all resolutions. |
| `site` | string \\| null |  | null | A site (ID, NEON code or name): adds whether it measures the variable, its measurement heights and instruments, and yearly coverage. (max length 200) |

**Result fields** (besides the common envelope)

| Field | Type | Description |
| --- | --- | --- |
| `variables` | array of VariableDescription |  |
| `page` | Page |  |

## amf_download_data

**Download AmeriFlux data (with consent).** Download AmeriFlux BASE-BADM, FLUXNET (FULLSET) or bulk BADM (BIF: AA-Flx/AA-Net) through AmeriFlux's logged route; stdio only. confirm=false (default) returns a plan: the exact text sent to the site PIs and the download log, eligible sites and the data policy; nothing is sent. Only after the user approves it, call again with confirm=true and accept_data_policy set to the plan's policy. Files are verified (size, ETag, zip CRC; sha256 sidecar). Next: amf_preview_data on a downloaded file.

| | |
| --- | --- |
| Surface | `data` |
| Download identity | required (stdio only) |
| Transports | stdio |
| Annotations | readOnly=false, destructive=false, idempotent=false, openWorld=true |
| Upstream endpoints | `POST amfcdn.lbl.gov/api/v1/data_download`<br>`HEAD ftp.fluxdata.org/.ameriflux_downloads/{product}/{file}`<br>`GET ftp.fluxdata.org/.ameriflux_downloads/{product}/{file}`<br>`GET amfcdn.lbl.gov/api/v1/data_availability/AmeriFlux/{product}/{policy}`<br>`GET amfcdn.lbl.gov/api/v1/DOI/{site}/{product}` |

**Inputs**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sites` | array of string | yes |  | Site IDs, NEON codes or names (up to 20); for product='BIF', AA-Flx (sites with flux data) or AA-Net (all sites). (min items 1; max items 20) |
| `product` | string |  | `"BASE-BADM"` | BASE-BADM, FLUXNET (FLUXNET-1F, FULLSET) or BIF (bulk BADM). FLUXNET2015 and FLUXNET-CH4 come from fluxnet.org (ameriflux://guide/fluxnet2015-access). |
| `policy` | string \\| null |  | null | CCBY4.0 or LEGACY. Default: the policy the sites require (Legacy if any selected site is Legacy). FLUXNET is CC-BY-4.0 only. |
| `profile` | string |  | `"default"` | Name of the configured identity profile (intended use and description). (pattern `^[A-Za-z0-9_.-]{1,64}$`) |
| `accept_data_policy` | string \\| null |  | null | With confirm=true: the policy code the plan showed (CCBY4.0 or LEGACY), meaning the user accepts it. |
| `confirm` | boolean |  | false | false: return the plan only. true: send the request, only after the user approved the plan. |
| `if_exists` | `skip` \\| `replace` |  | `"skip"` | A file already downloaded: skip keeps it; replace fetches it again unless it is identical. |

**Result fields** (besides the common envelope)

| Field | Type | Description |
| --- | --- | --- |
| `mode` | `plan` \\| `download` |  |
| `product` | string |  |
| `dataProduct` | string | The product AmeriFlux receives (BIF goes as BASE-BADM). |
| `policy` | PolicyOut |  |
| `eligible` | array of SiteChoice |  |
| `ineligible` | array of IneligibleSite |  |
| `disclosure` | DisclosureOut |  |
| `identity` | IdentityOut |  |
| `ready` | boolean | Whether confirm=true would send the request now. |
| `blockers` | array of string | What must change first. |
| `localCopies` | array of LocalCopy |  |
| `downloadDir` | string |  |
| `files` | array of FileOut |  |
| `skipped` | array of SkippedLink |  |
| `manifest` | ManifestOut \\| null |  |
| `piContactCount` | integer \\| null | PI contact emails AmeriFlux returned (never stored or shown). |
| `citations` | array of CitationRef |  |
| `totals` | Totals \\| null |  |

## amf_get_availability

**Get data availability per site and product.** 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.

| | |
| --- | --- |
| Surface | `availability` |
| Download identity | not needed |
| Transports | http, stdio |
| Annotations | readOnly=true, destructive=false, idempotent=true, openWorld=true |
| Upstream endpoints | `GET amfcdn.lbl.gov/api/v1/data_availability/{network}/{product}/{policy}`<br>`GET amfcdn.lbl.gov/api/v1/site_availability`<br>`GET amfcdn.lbl.gov/api/v2/site_info_display/AmeriFlux` |

**Inputs**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sites` | array of string \\| null |  | null | Site IDs, NEON codes or names (up to 50). Omit for every site with data. (max items 50) |
| `products` | array of string \\| null |  | null | BASE-BADM, BIF, FLUXNET, FLUXNET2015, FLUXNET-CH4. Default: the products of each site's collections (BASE-BADM and FLUXNET for AmeriFlux sites), or BASE-BADM when no sites are given. (max items 5) |
| `policy` | string \\| null |  | null | CCBY4.0, LEGACY or TIER2: only data usable under that policy. Default: every row labelled with its own policy. |
| `years` | string \\| null |  | null | Only years in this window: '2015' or '2010-2015'. |
| `limit` | integer |  | `50` | >= 1; <= 200 |
| `offset` | integer |  | `0` | >= 0 |

**Result fields** (besides the common envelope)

| Field | Type | Description |
| --- | --- | --- |
| `rows` | array of AvailabilityRow |  |
| `emptySites` | array of EmptySite | Requested sites without data for a product, and why. |
| `policyVerdict` | array of PolicyVerdict | The policy the requested sites must follow, per product, with obligations. |
| `combinedObligations` | array of ObligationOut | Every obligation once, across all collections. |
| `summary` | AvailabilitySummary |  |
| `page` | Page |  |

## amf_get_badm

**Get a site's BADM metadata.** 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.

| | |
| --- | --- |
| Surface | `metadata` |
| Download identity | not needed |
| Transports | http, stdio |
| Annotations | readOnly=true, destructive=false, idempotent=true, openWorld=true |
| Upstream endpoints | `GET amfcdn.lbl.gov/api/v2/site_info_display/AmeriFlux`<br>`GET amfcdn.lbl.gov/api/v1/site_display/FLUXNET/FLUXNET2015`<br>`GET amfcdn.lbl.gov/api/v1/site_display/FLUXNET/FLUXNET-CH4`<br>`GET amfcdn.lbl.gov/api/v1/DOI/{site}/{product}` |

**Inputs**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `site` | string | yes |  | Site ID (any case), NEON code, FLUXNET2015 old ID or name. (max length 200) |
| `include` | array of `site` \\| `team` \\| `disturbance` \\| `funding` \\| `references` \\| `instruments` \\| null |  | null | Sections; default all: site, team, disturbance, funding, references, instruments. |
| `variables` | array of string \\| null |  | null | Instruments: only these base names or exact variables (e.g. ['TA', 'SWC_1_1_1']). (max items 20) |
| `references_limit` | integer |  | `20` | Reference papers per page. (>= 1; <= 200) |
| `references_offset` | integer |  | `0` | >= 0 |
| `include_contacts` | boolean |  | false | Team emails, if the server allows it (privacy.allow_contact_emails). |

**Result fields** (besides the common envelope)

| Field | Type | Description |
| --- | --- | --- |
| `siteId` | string |  |
| `name` | string |  |
| `policy` | string \\| null |  |
| `site` | SiteGroup \\| null |  |
| `team` | array of TeamEntry \\| null |  |
| `disturbance` | array of string \\| null | Dominant disturbance and management (catalog summary of GRP_DM). |
| `fluxMeasurements` | array of string \\| null | Flux gas species measured. |
| `funding` | FundingGroup \\| null |  |
| `references` | ReferencesGroup \\| null |  |
| `instruments` | InstrumentsGroup \\| null |  |

## amf_get_citation

**Get citations and acknowledgments for sites.** 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.

| | |
| --- | --- |
| Surface | `citation` |
| Download identity | not needed |
| Transports | http, stdio |
| Annotations | readOnly=true, destructive=false, idempotent=true, openWorld=true |
| Upstream endpoints | `GET amfcdn.lbl.gov/api/v1/DOI/{site}/{product}` |

**Inputs**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sites` | array of string | yes |  | Site IDs (any case), NEON codes, FLUXNET2015 old IDs or names. (min items 1; max items 50) |
| `product` | string |  | `"BASE-BADM"` | BASE-BADM, BIF (cited with the BASE DOI), FLUXNET (FLUXNET-1F) or FLUXNET2015. FLUXNET-CH4 citations arrive in v0.2. |
| `include_bibtex` | boolean |  | false | Add a BibTeX @misc entry per citation. |

**Result fields** (besides the common envelope)

| Field | Type | Description |
| --- | --- | --- |
| `product` | string |  |
| `citations` | array of CitationOut |  |
| `missing` | array of MissingCitation | Requested sites without a citation, and why. |
| `effectivePolicy` | EffectivePolicyOut |  |
| `acknowledgments` | array of AcknowledgmentOut |  |
| `siteFunding` | array of SiteFunding | Legacy policy: acknowledge each site's funding (DOI record sponsors). |
| `dataAvailability` | DataAvailabilityOut \\| null |  |
| `processingReferences` | array of ReferenceOut |  |
| `bibtexElided` | boolean \\| null |  |
| `page` | Page |  |

## amf_get_site

**Get one AmeriFlux or FLUXNET site.** 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.

| | |
| --- | --- |
| Surface | `discovery` |
| Download identity | not needed |
| Transports | http, stdio |
| Annotations | readOnly=true, destructive=false, idempotent=true, openWorld=true |
| Upstream endpoints | `GET amfcdn.lbl.gov/api/v2/site_info_display/AmeriFlux`<br>`GET amfcdn.lbl.gov/api/v1/site_display/FLUXNET/FLUXNET2015`<br>`GET amfcdn.lbl.gov/api/v1/site_display/FLUXNET/FLUXNET-CH4` |

**Inputs**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `site` | string | yes |  | Site ID (US-Ha1, any case), NEON code (SRER), FLUXNET2015 old ID (DK-ZaF) or site name. (max length 200) |
| `include` | array of `description` \\| `team` \\| `variables` \\| `disturbance` \\| null |  | null | Optional sections; default all: description, team, variables, disturbance. |
| `include_contacts` | boolean |  | false | Include team emails, if the server allows it (privacy.allow_contact_emails). |

**Result fields** (besides the common envelope)

| Field | Type | Description |
| --- | --- | --- |
| `siteId` | string |  |
| `name` | string |  |
| `collections` | array of string |  |
| `status` | string \\| null |  |
| `tower` | Tower |  |
| `location` | Location |  |
| `ecosystem` | Ecosystem |  |
| `policy` | PolicyInfo |  |
| `dois` | Dois |  |
| `products` | SiteProducts |  |
| `networks` | array of string |  |
| `crosslinks` | Crosslinks |  |
| `gasSpecies` | array of string |  |
| `description` | string \\| null |  |
| `disturbance` | array of string \\| null |  |
| `team` | array of TeamEntry \\| null |  |
| `teamTotal` | integer \\| null |  |
| `baseVariables` | array of string \\| null | FP Standard base names in the site's BASE data (up to 60). |
| `baseVariablesTotal` | integer \\| null |  |

## amf_list_files

**List local AmeriFlux and FLUXNET files.** 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.

| | |
| --- | --- |
| Surface | `local` |
| Download identity | not needed |
| Transports | stdio |
| Annotations | readOnly=true, destructive=false, idempotent=true, openWorld=false |
| Upstream endpoints | none |

**Inputs**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `path` | string \\| null |  | null | A folder or archive inside the download directory or a local root; default: every root. (max length 1000) |
| `family` | array of `base` \\| `bif` \\| `fluxnet` \\| `fluxnet2015` \\| `fluxnet_ch4` \\| null |  | null | Only these families. |
| `site` | string \\| null |  | null | Only this site ID (any case). (max length 20) |
| `include_members` | boolean |  | true | Classify the members of each archive. |
| `limit` | integer |  | `50` | >= 1; <= 200 |
| `offset` | integer |  | `0` | >= 0 |

**Result fields** (besides the common envelope)

| Field | Type | Description |
| --- | --- | --- |
| `roots` | array of string |  |
| `files` | array of FileEntry |  |
| `facets` | ListFacets |  |
| `unrecognized` | integer | Files skipped because their names are not ours. |
| `membersElided` | boolean \\| null |  |
| `page` | Page |  |

## amf_ping

**Check ameriflux-mcp status.** 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.

| | |
| --- | --- |
| Surface | `core` |
| Download identity | not needed |
| Transports | http, stdio |
| Annotations | readOnly=true, destructive=false, idempotent=true, openWorld=true |
| Upstream endpoints | `GET amfcdn.lbl.gov/api/v1/fp_var` |

**Inputs**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `check_api` | boolean |  | false | Also make one small request to the AmeriFlux API (the FP Standard variable list) to confirm connectivity. |

**Result fields** (besides the common envelope)

| Field | Type | Description |
| --- | --- | --- |
| `pong` | `ok` |  |
| `version` | string |  |
| `protocolVersion` | string |  |
| `transport` | `stdio` \\| `http` |  |
| `identity` | IdentityReport |  |
| `identityRequiredTools` | array of string | Registered tools that need the download identity (auth_required without it). |
| `downloadsEnabled` | boolean |  |
| `downloadDir` | string \\| null |  |
| `localRoots` | array of string \\| null | Directories the local file tools may read (stdio only). |
| `endpoints` | Endpoints |  |
| `cache` | CacheReport |  |
| `upstream` | UpstreamCheck \\| null | Present when check_api was requested. |

## amf_preview_data

**Preview a local AmeriFlux or FLUXNET data file.** 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.

| | |
| --- | --- |
| Surface | `local` |
| Download identity | not needed |
| Transports | stdio |
| Annotations | readOnly=true, destructive=false, idempotent=true, openWorld=false |
| Upstream endpoints | none |

**Inputs**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `file` | string \\| null |  | null | A file or 'archive.zip::member.csv', relative to a local root (see amf_list_files). Or give site and product instead. (max length 1000) |
| `site` | string \\| null |  | null | Newest local file of this site. (max length 20) |
| `product` | string \\| null |  | null | With site: BASE-BADM (default), FLUXNET or FLUXNET2015. |
| `resolution` | `HH` \\| `HR` \\| `DD` \\| `WW` \\| `MM` \\| `YY` \\| null |  | null | Member of an archive to read (default HH; HR sites match HH). |
| `columns` | array of string \\| null |  | null | Columns by name (default: up to 80 in summaries). (max items 60) |
| `start` | string \\| null |  | null | First time, e.g. 2012, 2012-06, 2012-06-01T12:00. |
| `end` | string \\| null |  | null | Last time (inclusive): end='2012' keeps all of 2012. |
| `mode` | `summary` \\| `rows` |  | `"summary"` | summary: per-column statistics; rows: a window of rows. |
| `max_rows` | integer |  | `100` | Rows per page (capped by the server). (>= 1; <= 5000) |
| `offset` | integer |  | `0` | Rows to skip within the time window. (>= 0) |
| `qc_max` | integer \\| null |  | null | HH/HR FLUXNET: keep values whose _QC flag is at most this. (>= 0; <= 3) |
| `qc_min_fraction` | number \\| null |  | null | DD and coarser FLUXNET: keep values whose _QC fraction is at least this. (>= 0; <= 1) |
| `to_utc` | boolean |  | false | Add UTC timestamps (offset from the site's BIF). |
| `view` | `full` \\| `subset` |  | `"full"` | subset: only FLUXNET2015 SUBSET variables (AmeriFlux FLUXNET files). |

**Result fields** (besides the common envelope)

| Field | Type | Description |
| --- | --- | --- |
| `fileInfo` | FileInfo |  |
| `columns` | array of ColumnSummary |  |
| `rowColumns` | array of string \\| null |  |
| `rows` | array of array of number \\| string \\| null \\| null |  |
| `scan` | ScanInfo |  |
| `page` | Page \\| null |  |

## amf_read_bif

**Read a local BADM (BIF) file.** 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.

| | |
| --- | --- |
| Surface | `local` |
| Download identity | not needed |
| Transports | stdio |
| Annotations | readOnly=true, destructive=false, idempotent=true, openWorld=false |
| Upstream endpoints | none |

**Inputs**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `file` | string \\| null |  | null | A BIF xlsx or CSV, or an archive holding one (BASE-BADM, FLUXNET), relative to a local root. Or give site. (max length 1000) |
| `site` | string \\| null |  | null | The newest local BIF of this site. (max length 20) |
| `groups` | array of string \\| null |  | null | Only these groups, e.g. ['GRP_UTC_OFFSET', 'GRP_DOI']. (max items 40) |
| `site_id` | string \\| null |  | null | In a bulk file (AA-Flx, AA-Net): only this site. (max length 20) |
| `include_contacts` | boolean |  | false | Emails and addresses, if the server allows it (privacy settings). |
| `limit` | integer |  | `100` | >= 1; <= 500 |
| `offset` | integer |  | `0` | >= 0 |

**Result fields** (besides the common envelope)

| Field | Type | Description |
| --- | --- | --- |
| `fileInfo` | BifFileInfo |  |
| `entries` | array of BifEntryOut |  |
| `utcOffsets` | array of UtcOffsetOut |  |
| `citations` | array of BifCitation |  |
| `acknowledgments` | array of BifAcknowledgment |  |
| `withheld` | integer | Personal values withheld (emails, addresses, land owners). |
| `page` | Page |  |

## amf_search_sites

**Search AmeriFlux and FLUXNET sites.** 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.

| | |
| --- | --- |
| Surface | `discovery` |
| Download identity | not needed |
| Transports | http, stdio |
| Annotations | readOnly=true, destructive=false, idempotent=true, openWorld=true |
| Upstream endpoints | `GET amfcdn.lbl.gov/api/v2/site_info_display/AmeriFlux`<br>`GET amfcdn.lbl.gov/api/v1/site_display/FLUXNET/FLUXNET2015`<br>`GET amfcdn.lbl.gov/api/v1/site_display/FLUXNET/FLUXNET-CH4` |

**Inputs**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `query` | string \\| null |  | null | Words matched against site ID, name, state, country, NEON code and networks (every word must match; prefixes count, e.g. 'harv'). (max length 200) |
| `collection` | `ameriflux` \\| `fluxnet2015` \\| `fluxnet_ch4` \\| `all` |  | `"all"` | ameriflux (856 sites), fluxnet2015 (212), fluxnet_ch4 (81) or all. |
| `product` | string \\| null |  | null | Only sites with data in BASE-BADM, FLUXNET (FLUXNET-1F), FLUXNET2015 or FLUXNET-CH4. |
| `policy` | string \\| null |  | null | CCBY4.0, LEGACY (AmeriFlux) or TIER2 (Tier-Two-only FLUXNET2015/CH4 sites). CC-BY-4.0, Legacy and Tier2 spellings are accepted. |
| `igbp` | array of string \\| null |  | null | IGBP classes, e.g. ['DBF', 'ENF'] (see the vocabulary). (max items 17) |
| `koeppen` | array of string \\| null |  | null | Köppen codes or prefixes, e.g. ['Dfb'] or ['B']. (max items 30) |
| `country` | array of string \\| null |  | null | Country codes as in site IDs ('US', 'CA', 'BR') or names ('Canada'). (max items 50) |
| `state` | array of string \\| null |  | null | US state or province codes, e.g. ['NM', 'AZ']. (max items 60) |
| `status` | `active` \\| `inactive` \\| `any` |  | `"any"` | AmeriFlux tower status. |
| `network` | array of string \\| null |  | null | Member networks besides AmeriFlux, e.g. ['NEON'], ['LTER'], ['Phenocam']. (max items 12) |
| `bbox` | array of number \\| null |  | null | [west, south, east, north] in decimal degrees (no antimeridian crossing). (min items 4; max items 4) |
| `near` | Near \\| null |  | null | Sites within radius_km of a point. |
| `years` | string \\| null |  | null | Data overlapping a year or range ('2015', '2010-2015') in the chosen product (default: BASE for AmeriFlux sites, the FLUXNET tier range otherwise). |
| `min_years` | integer \\| null |  | null | At least this many data years. (>= 1; <= 100) |
| `base_variable` | array of string \\| null |  | null | FP Standard base names every site must measure, e.g. ['FCH4', 'SWC']. (max items 20) |
| `gas` | array of string \\| null |  | null | Flux gas species, e.g. ['CH4'] or ['CO2', 'H2O']. (max items 6) |
| `sort` | `site_id` \\| `name` \\| `years` \\| `distance` \\| null |  | null | Default: distance with near, relevance with query, else site_id. |
| `limit` | integer |  | `25` | >= 1; <= 200 |
| `offset` | integer |  | `0` | >= 0 |

**Result fields** (besides the common envelope)

| Field | Type | Description |
| --- | --- | --- |
| `sites` | array of SiteSummary |  |
| `facets` | Facets | Counts over every match, not just this page. |
| `page` | Page |  |

## amf_search_variables

**Search the FP Standard and FLUXNET variable dictionaries.** 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.

| | |
| --- | --- |
| Surface | `variables` |
| Download identity | not needed |
| Transports | http, stdio |
| Annotations | readOnly=true, destructive=false, idempotent=true, openWorld=true |
| Upstream endpoints | `GET amfcdn.lbl.gov/api/v1/fp_var` |

**Inputs**

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `query` | string \\| null |  | null | Words matched against name, description and units (prefixes count: 'soil temp', 'GPP', 'methane'). (max length 200) |
| `dictionary` | `fp` \\| `fluxnet` \\| `fluxnet_fullset` \\| `fluxnet_subset` \\| `all` |  | `"all"` | fp (FP Standard, BASE), fluxnet (AmeriFlux FLUXNET, ONEFlux v1.3), fluxnet_fullset / fluxnet_subset (FLUXNET2015), or all. |
| `category` | string \\| null |  | null | FP type (GASES, MET_RAD, MET_SOIL, …) or FLUXNET section (PARTITIONING, NET ECOSYSTEM EXCHANGE, …); prefixes count. (max length 60) |
| `resolution` | string \\| null |  | null | HH (also HR), DD, WW, MM or YY: FLUXNET variables available at it, with its units. |
| `limit` | integer |  | `25` | >= 1; <= 200 |
| `offset` | integer |  | `0` | >= 0 |

**Result fields** (besides the common envelope)

| Field | Type | Description |
| --- | --- | --- |
| `variables` | array of VariableSummary |  |
| `facets` | VariableFacets |  |
| `page` | Page |  |

---8<--- https://idss-mesa.github.io/ameriflux-mcp/tools/roadmap/

---
title: "Roadmap"
description: "The twelve planned ameriflux-mcp tools, the build step that delivers each, and which work over HTTP or need a download identity."
type: Reference
tags:
  - tools
  - roadmap
  - planning
generated:
  by: "claude/opus-5.5"
  at: "2026-10-24T00:00:00Z"
sources:
  - id: design
    resource: "https://github.com/idss-mesa/ameriflux-mcp/blob/main/DESIGN.md"
    title: "ameriflux-mcp design (tool surface and build order)"
    author: "team:idss-mesa"
  - id: research
    resource: "https://github.com/idss-mesa/ameriflux-mcp/blob/main/RESEARCH.md"
    title: "ameriflux-mcp verified research"
    author: "team:idss-mesa"
status: draft
stale_after: "2027-01-23T00:00:00Z"
---

# Roadmap

ameriflux-mcp v0.1.0 was built in eight steps, one pull request each[^design]. This
page records what each step delivered and what comes next; the generated
[tool reference](reference.md) is the authoritative list of tools.

## Build steps

| Step | Delivers | Status |
| --- | --- | --- |
| 1 | Design, verified API research, a read-only API probe | done |
| 2 | The MCP core ported from edi-mcp, configuration, identity settings, `amf_ping`, CI | done |
| 3 | AmeriFlux API client, rate limiting, cache, site catalog and name resolution, policy engine, recorded test fixtures | done |
| 4 | Site discovery and availability tools | done |
| 5 | Variable, citation and BADM tools | done |
| 6 | Local file readers and previews | done |
| 7 | The download tool | done |
| 8 | Prompts, resources, full documentation, Docker image, PyPI release v0.1.0 | done |

The [tool reference](reference.md) is generated from the server's registry and lists
exactly the tools the current build offers.

## Planned tools

| Tool | Step | HTTP | What it does |
| --- | --- | --- | --- |
| `amf_ping` | 2 | yes | Version, protocol, transport; which identity fields are configured (booleans only); whether the AmeriFlux API answers. |
| `amf_search_sites` | 4 | yes | Find AmeriFlux (856 sites), FLUXNET2015 (212) and FLUXNET-CH4 (81) towers[^research] by name, place, bounding box, IGBP ecosystem class, Köppen climate, years, product, data policy and measured variables. |
| `amf_get_site` | 4 | yes | One site by ID, name, NEON code or FLUXNET2015 alias: location, ecosystem, climate, data policy, DOIs, years per product, team (no emails by default) and links to NEON and EDI. |
| `amf_get_availability` | 4 | yes | Published years per site, product and policy, with the sites that have no data listed separately and the effective policy of the selection. |
| `amf_search_variables` | 5 | yes | Search the FP Standard (145 base names) and FLUXNET FULLSET/SUBSET dictionaries, with units per time resolution. |
| `amf_describe_variables` | 5 | yes | Parse names such as `TA_F_1_1_1` or `GPP_NT_VUT_REF`: qualifiers, gap-filling and partitioning method, QC scheme, units by resolution, sign convention, measurement heights. |
| `amf_get_citation` | 5 | yes | The versioned citation AmeriFlux recommends per site, required acknowledgments, the obligations of the CC-BY-4.0, Legacy or Tier 2 policy, and a data-availability sentence. |
| `amf_get_badm` | 5 | yes | Site metadata (BADM) the API exposes: location, IGBP, climate, team, disturbance and management, funding, reference papers, instruments and measurement heights. |
| `amf_download_data` | 7 | no | BASE-BADM, AmeriFlux FLUXNET and bulk BADM through AmeriFlux's logged download route: a plan first, then `confirm=true`; checksummed files. Needs a [download identity](../getting-started/identity.md). |
| `amf_list_files` | 6 | no | Classify downloaded zips and CSVs by product, site, resolution, years and version. |
| `amf_preview_data` | 6 | no | Column summaries and row windows from local BASE, FLUXNET and FLUXNET2015 files, with time windows, QC filtering, missing values as nulls and a SUBSET view. |
| `amf_read_bif` | 6 | no | Read BADM Interchange Format files (xlsx or CSV), including UTC offsets and the site's DOI citation. |

## Data products covered

| Product | Discover | Availability | Cite | Download | Read locally |
| --- | --- | --- | --- | --- | --- |
| AmeriFlux BASE (BASE-BADM) | yes | yes | yes | yes | yes |
| AmeriFlux BADM / BIF | yes | yes (membership) | yes (BASE DOI) | yes (bulk) | yes |
| AmeriFlux FLUXNET (FLUXNET-1F) | yes | yes | yes | yes | yes |
| FLUXNET2015 FULLSET / SUBSET | yes | yes | yes | no (login-protected form) | yes |
| FLUXNET-CH4 | yes | yes | v0.2 | no | v0.2 |

## After v0.1.0

Version 0.2 focuses on analysis: server-side summaries by year, month or hour with QC
handling, Parquet export with a hand-off to the CyVerse Data Store and mesa-ducklake,
DuckDB as an optional extra, FLUXNET-CH4 readers and citations, and possibly the
European and Australian networks served through the FLUXNET Shuttle.

[^design]: ameriflux-mcp design. <https://github.com/idss-mesa/ameriflux-mcp/blob/main/DESIGN.md>
[^research]: ameriflux-mcp verified research. <https://github.com/idss-mesa/ameriflux-mcp/blob/main/RESEARCH.md>

---8<--- https://idss-mesa.github.io/ameriflux-mcp/tools/variables/

---
title: "Variables"
description: "Find and decode AmeriFlux BASE and FLUXNET variable names with amf_search_variables and amf_describe_variables: qualifiers, units per resolution, QC, heights."
type: Guide
tags:
  - tools
  - variables
  - fluxnet
  - qa-qc
generated:
  by: "claude/opus-5.5"
  at: "2026-10-24T00:00:00Z"
sources:
  - id: research
    resource: "https://github.com/idss-mesa/ameriflux-mcp/blob/main/RESEARCH.md"
    title: "ameriflux-mcp verified research (section 7)"
    author: "team:idss-mesa"
  - id: design
    resource: "https://github.com/idss-mesa/ameriflux-mcp/blob/main/DESIGN.md"
    title: "ameriflux-mcp design (D35)"
    author: "team:idss-mesa"
  - id: amf-variables
    resource: "https://ameriflux.lbl.gov/data/aboutdata/data-variables/"
    title: "AmeriFlux data variables"
    author: "team:ameriflux"
  - id: fullset
    resource: "https://fluxnet.org/data/fluxnet2015-dataset/fullset-data-product/"
    title: "FLUXNET2015 FULLSET data product"
    author: "team:fluxnet"
status: stable
stale_after: "2027-04-24T00:00:00Z"
---

# Variables

Flux files name every column with a code such as `TA_F_1_1_1` or `GPP_NT_VUT_REF`. Two
tools turn those codes into something you can use. Neither needs an account, and both
work over stdio and HTTP. Inputs and result fields are in the
[Tool reference](reference.md).

## Two kinds of name

**BASE names** (AmeriFlux BASE, the FP Standard[^amf-variables]) are a base name and
qualifiers:

```
<BASE NAME>[_PI][_QC][_F][_IU][_H_V_R | _H_V_A | _#][_SD | _N]
```

| Part | Meaning |
| --- | --- |
| Base name | One of about 145 FP Standard names (`TA`, `FC`, `SW_IN`, `FETCH_70`, `FC_SSITC_TEST`) |
| `_PI` | Filtered or gap-filled by the tower team, independently of the network |
| `_QC` | Quality flag from AmeriFlux's central QA/QC |
| `_F` | Gap-filled |
| `_IU` | Instrument units (counts, mV) rather than standard units |
| `_H_V_R` | One sensor: horizontal position, vertical position (1 = highest or shallowest), replicate |
| `_H_V_A` | Replicates at one position, averaged |
| `_#` | Layer aggregate across horizontal positions |
| `_SD`, `_N` | Standard deviation and number of sensors in an aggregate |

**FLUXNET names** (FLUXNET2015 FULLSET and SUBSET[^fullset], and the AmeriFlux FLUXNET
product made with ONEFlux v1.3) add processing tokens: `_F_MDS` (gap-filled with MDS),
`_ERA` (downscaled from reanalysis), `_VUT`/`_CUT` (USTAR threshold varies by year or is
constant), `_REF` and the percentiles `_05` … `_95`, `_NT`/`_DT`/`_SR` (partitioning
method), `_RANDUNC`, `_CORR`, `_DAY`/`_NIGHT`, `_QC`.

## Units and QC change with resolution

FLUXNET files come at HH (half-hourly or hourly), DD, WW, MM and YY, and one name means
different units at each[^research]:

| Variable | HH | DD, WW, MM | YY |
| --- | --- | --- | --- |
| `NEE_VUT_REF`, `GPP_NT_VUT_REF`, `RECO_NT_VUT_REF` | µmolCO2 m-2 s-1 | gC m-2 d-1 | gC m-2 y-1 |
| `P_F` | mm (per interval) | mm d-1 | mm y-1 |
| `TA_F_MDS_QC` | 0 measured, 1 good, 2 medium, 3 poor gap-fill | fraction of measured and good data | fraction |

Every FLUXNET result carries `unitsByResolution`; pass `resolution` to get one unit and
the QC meaning at that resolution. Negative NEE and FC are uptake; GPP and RECO are
positive.

## amf_search_variables

Words match names, descriptions and units (prefixes count). Choose a `dictionary`:

| `dictionary` | Contents |
| --- | --- |
| `fp` | The FP Standard list for BASE, read live from the AmeriFlux API with its QA/QC ranges (`plausibleRange`) |
| `fluxnet` | Names the AmeriFlux FLUXNET product defines (ONEFlux v1.3) |
| `fluxnet_fullset`, `fluxnet_subset` | FLUXNET2015 FULLSET (232 names) and SUBSET (72) |
| `all` | All of the above (default) |

`category` filters by FP type (`GASES`, `MET_SOIL`) or FLUXNET section (`PARTITIONING`,
`SUNDOWN`); `resolution` keeps the FLUXNET names produced at it.

```json
{"tool": "amf_search_variables", "arguments": {"query": "soil temperature"}}
{"tool": "amf_search_variables", "arguments": {"query": "GPP", "dictionary": "fluxnet_subset", "resolution": "DD"}}
```

Dictionary names with `XX` or `#` stand for many columns: `NEE_VUT_XX` is `NEE_VUT_05`
to `NEE_VUT_95`, and `TS_F_MDS_#` is `TS_F_MDS_1` (shallowest), `TS_F_MDS_2`, …

## amf_describe_variables

Up to 20 names per call. Each result gives the base name and its FP definition, every
qualifier or token with its meaning, the position, the units, the FLUXNET definition
(with the dictionary key: `NEE_VUT_05` is `NEE_VUT_XX`), a sign convention where one
applies, and `didYouMean` for names it does not recognize. A name valid in both grammars
(`TA_F`) gets both readings, with a note.

With `site`, each name also gets:

- whether the site's BASE data include the base name (from the catalog);
- sensor heights and instruments from AmeriFlux's measurement-height file;
- yearly coverage per column from amerifluxr's snapshot, marked with its date
  (2025-10-20 as of this writing; it lags the current BASE release).

```json
{"tool": "amf_describe_variables", "arguments": {"names": ["GPP_NT_VUT_REF", "TA_F_MDS_QC"], "resolution": "DD"}}
{"tool": "amf_describe_variables", "arguments": {"names": ["TA", "SWC_1_1_1"], "site": "US-Ha1"}}
```

The first call with `site` downloads the measurement-height file (about 2.3 MB) and the
coverage snapshot (about 6.5 MB). Both are cached: heights for 24 hours, coverage for
7 days.

## Sources and resources

| URI | Content |
| --- | --- |
| `ameriflux://guide/variable-grammar` | The grammar on this page, for agents |
| `ameriflux://reference/fp-variables` | The FP Standard list (live, or the bundled snapshot when the API is unreachable) |
| `ameriflux://reference/fluxnet-variables` | The FLUXNET dictionary with units and notes per resolution |

The FLUXNET dictionary is built by `scripts/build_variable_dictionaries.py` from the
FLUXNET2015 webdoc dictionaries and ONEFlux's `var_info_definitions` files. The micro
sign is restored where ONEFlux stores it as a replacement character[^design].

[^research]: ameriflux-mcp verified research. <https://github.com/idss-mesa/ameriflux-mcp/blob/main/RESEARCH.md>
[^design]: ameriflux-mcp design. <https://github.com/idss-mesa/ameriflux-mcp/blob/main/DESIGN.md>
[^amf-variables]: AmeriFlux data variables. <https://ameriflux.lbl.gov/data/aboutdata/data-variables/>
[^fullset]: FLUXNET2015 FULLSET data product. <https://fluxnet.org/data/fluxnet2015-dataset/fullset-data-product/>

---8<--- https://idss-mesa.github.io/ameriflux-mcp/about/ai-agents/

---
title: "For AI agents"
description: "How agents should read this site (llms.txt, per-page Markdown, OKF trust signals) and why to call the ameriflux-mcp server for flux data."
type: Reference
tags:
  - about
  - ai-agents
  - OKF
  - llms.txt
generated:
  by: "claude/opus-5.5"
  at: "2026-10-23T00:00:00Z"
sources:
  - id: okf-spec
    resource: "https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md"
    title: "Open Knowledge Format (OKF) v0.2 specification"
    author: "team:google-cloud"
  - id: llmstxt
    resource: "https://llmstxt.org"
    title: "The /llms.txt convention"
    author: "team:answer-ai"
  - id: mcp-spec
    resource: "https://modelcontextprotocol.io/specification/2026-07-28"
    title: "Model Context Protocol specification, 2026-07-28"
    author: "team:modelcontextprotocol"
status: stable
---

# For AI agents

This site is published for people **and** for AI agents. The documentation
source is an [Open Knowledge Format (OKF) v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md){target=_blank}
knowledge bundle[^okf-spec], and the deployed site exposes that structure
directly. If you are an agent (or you are wiring one up), consume the
documentation through the endpoints below rather than scraping rendered HTML.

## This site documents an MCP server

ameriflux-mcp *is* an agent tool. If what you actually want is AmeriFlux or
FLUXNET data — sites, availability, variables, citations — do not scrape these
pages: connect to the server and call its tools. Locally, run it over `stdio`
(`claude mcp add ameriflux -s user -- ameriflux-mcp --transport stdio`); against a
hosted instance, use Streamable HTTP at `https://<host>/mcp`
(`claude mcp add --transport http ameriflux https://<host>/mcp`). Read
`ameriflux://guide/agent-workflow` first; the
[prompts](../tools/prompts-and-resources.md) package the usual tasks. The server
implements MCP 2026-07-28[^mcp-spec]: `server/discover` and `tools/list`
return the live, authoritative tool catalogue with JSON Schema inputs and
outputs, and every list result carries cache hints. Use this documentation
to learn *how* to use the server; use the server to get the data.

## Entry points

All URLs are under `https://idss-mesa.github.io/ameriflux-mcp/`.

| Endpoint | What you get |
| -------- | ------------ |
| [`llms.txt`](../llms.txt) — `https://idss-mesa.github.io/ameriflux-mcp/llms.txt` | Linked outline of every page with one-line descriptions ([llms.txt convention](https://llmstxt.org){target=_blank}[^llmstxt]) |
| [`llms-full.txt`](../llms-full.txt) — `https://idss-mesa.github.io/ameriflux-mcp/llms-full.txt` | The entire corpus in one file: every page's Markdown with frontmatter, each prefixed by its canonical URL |
| Any page URL + `index.md` | That page's Markdown source with full OKF frontmatter, e.g. `https://idss-mesa.github.io/ameriflux-mcp/getting-started/install/index.md` |
| `https://idss-mesa.github.io/ameriflux-mcp/sitemap.xml`, `https://idss-mesa.github.io/ameriflux-mcp/robots.txt` | Standard crawl surface; `robots.txt` welcomes AI fetchers and repeats these pointers |
| [`tools/reference/`](../tools/reference.md) — `https://idss-mesa.github.io/ameriflux-mcp/tools/reference/` | The tool catalogue generated from the server's registry: every tool's inputs, result fields, endpoints and identity requirement |
| [`tools/roadmap/`](../tools/roadmap.md) — `https://idss-mesa.github.io/ameriflux-mcp/tools/roadmap/` | The planned tools and the build step that delivers each |
| [Source repository](https://github.com/idss-mesa/ameriflux-mcp){target=_blank} | The bundle itself under `docs/`, plus `CLAUDE.md` with the rules coding agents follow when editing the code |

Every rendered page also declares its Markdown twin and OKF signals in its
HTML `<head>`, as `okf:`-prefixed meta tags named after the frontmatter keys
(`type`, `status`, `trust-tier`, `generated-at`, `generated-by`,
`stale-after`) — for example:

```html
<link rel="alternate" type="text/markdown" href="index.md">
<meta name="okf:status" content="stable">
<meta name="okf:trust-tier" content="unverified">
<meta name="okf:generated-at" content="2026-10-23T00:00:00Z">
<meta name="okf:generated-by" content="claude/opus-5.5">
<meta name="okf:stale-after" content="2027-04-23T00:00:00Z">
```

The page's `type` is exposed the same way, so a crawler can filter by kind of
page (Guide, Reference, Policy, ...) without parsing frontmatter.

## Reading the OKF frontmatter

Each content page's YAML frontmatter answers the questions an agent should
ask before relying on it[^okf-spec]:

* **What is this?** — `type` (`Guide`, `Tutorial`, `Reference`, `Policy`,
  `MCP Tool Reference`), `title`, `description`, `tags`.
* **Where did it come from?** — `generated: { by, at }` records the actor
  that produced the current text and when it last changed meaningfully;
  `sources` lists the load-bearing external references (`id`, `resource`
  URL, `title`, `author`). Footnotes in the body cite sources by their `id`.
* **How much should I trust it?** — the `verified` key (see trust tiers
  below). Its absence is meaningful: the page has not been confirmed by
  anyone other than its generator.
* **Is it still true?** — `status` (`stable` is the default; `draft` needs
  review; `deprecated` is kept for history only) and `stale_after`, an
  ISO 8601 instant after which the page should be re-checked. Pages that
  state facts AmeriFlux, FLUXNET or the MCP project may change — data
  policies, endpoints, SDK versions — carry one.

Actors follow OKF §7: `<producer>/<version>` for agents and tools (for
example `claude/opus-5.5`), `human:<id>` for a person, `process:<id>` for an
automated job such as the generated tool reference.

## Trust tiers

| `verified` key | Tier | Meaning |
| --- | --- | --- |
| absent | **unverified** | Generated content nobody has confirmed against its sources. Most pages on this site start here. |
| present, non-`human:` actors only | **machine-confirmed** | An automated check (a CI job, a live smoke test) confirmed the content. |
| present with a `human:<id>` actor | **human-reviewed** | A maintainer read and confirmed the page. Prefer these when answers conflict. |

Only humans add `verified:` entries; a generator never does. The
`okf:trust-tier` meta tag carries the derived tier for quick filtering.

## Answering user questions

Ground answers in this documentation and cite the page URL (for example
`https://idss-mesa.github.io/ameriflux-mcp/getting-started/install/`). For
anything about the *data* — site IDs, years, variables, DOIs, policies — call
the server or [AmeriFlux](https://ameriflux.lbl.gov){target=_blank}
rather than guessing from prose. When the corpus does not answer a question
about ameriflux-mcp itself, direct users to the
[GitHub issue tracker](https://github.com/idss-mesa/ameriflux-mcp/issues){target=_blank}.

[^okf-spec]: Open Knowledge Format (OKF) v0.2 specification. <https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md>
[^llmstxt]: The /llms.txt convention. <https://llmstxt.org>
[^mcp-spec]: Model Context Protocol specification, 2026-07-28. <https://modelcontextprotocol.io/specification/2026-07-28>

---8<--- https://idss-mesa.github.io/ameriflux-mcp/about/citing-ameriflux/

---
title: "Citing AmeriFlux and FLUXNET data"
description: "How to cite AmeriFlux BASE, AmeriFlux FLUXNET and FLUXNET2015 data: per-site DOIs, required acknowledgments, policy obligations, and citing ameriflux-mcp."
type: Policy
tags:
  - about
  - citation
  - data-policy
  - doi
generated:
  by: "claude/opus-5.5"
  at: "2026-10-24T00:00:00Z"
sources:
  - id: amf-policy
    resource: "https://ameriflux.lbl.gov/data/data-policy/"
    title: "AmeriFlux Data Policy"
    author: "team:ameriflux"
  - id: fluxnet-policy
    resource: "https://fluxnet.org/data/data-policy/"
    title: "FLUXNET Data Policy"
    author: "team:fluxnet"
  - id: chu-2023
    resource: "https://doi.org/10.1038/s41597-023-02531-2"
    title: "Chu et al. (2023), AmeriFlux BASE data pipeline to support network growth and data sharing, Sci Data 10, 614"
    author: "Chu, H. et al."
  - id: pastorello-2020
    resource: "https://doi.org/10.1038/s41597-020-0534-3"
    title: "Pastorello et al. (2020), The FLUXNET2015 dataset and the ONEFlux processing pipeline for eddy covariance data, Sci Data 7, 225"
    author: "Pastorello, G. et al."
status: stable
stale_after: "2027-04-23T00:00:00Z"
---

# Citing AmeriFlux and FLUXNET data

AmeriFlux and FLUXNET data come from individual tower teams, and the data policies ask
you to credit each site you use. `amf_get_citation` assembles everything on this page
for a list of sites; this page explains what it returns and why. The text below follows
the AmeriFlux data policy (CC-BY-4.0 license revised December 2025) and the FLUXNET data
policy as read on 2026-10-22[^amf-policy][^fluxnet-policy]; the policy pages are
authoritative.

## One citation per site

Every AmeriFlux product of every site has its own DOI under `10.17190/AMF/`, and every
FLUXNET2015 site one under `10.18140/FLX/`. Cite each site in the reference list, not in
supplementary material. AmeriFlux's recommended form includes the product version:

> J. William Munger, Shawn Urbanski, Michael Golden, Carol Barford, Jaclyn Matthes,
> Steven Wofsy (2026), AmeriFlux BASE US-Ha1 Harvard Forest EMS Tower (HFR1), Ver. 28-5,
> AmeriFlux AMP, (Dataset). https://doi.org/10.17190/AMF/1246059

> … (2026), 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 version, year and publisher in this form differ from what generic DOI services
(DataCite, doi.org) return, so prefer AmeriFlux's form. BADM metadata downloaded with a
product is cited with that product's DOI. AmeriFlux does not publish ready-made citation
text for FLUXNET2015 sites; `amf_get_citation` builds it from the site's DOI record in the
form the FLUXNET DOI landing page shows:

> J. William Munger, Shawn Urbanski, Michael Golden, Carol Barford, Jaclyn Matthes,
> Steven Wofsy (1991-2012) FLUXNET2015 US-Ha1 Harvard Forest EMS Tower (HFR1), Dataset.
> https://doi.org/10.18140/FLX/1440071

## Acknowledgments

For **CC-BY-4.0** AmeriFlux data:

> Funding for the AmeriFlux data service was provided by the U.S. Department of Energy
> Office of Science.

For **Legacy** data the wording names the data *portal*:

> Funding for the AmeriFlux data portal was provided by the U.S. Department of Energy
> Office of Science.

When you use the **AmeriFlux FLUXNET** product, add:

> FLUXNET data products were produced and harmonized by eddy covariance regional
> networks and data processing centers, including AmeriFlux, ChinaFlux, European Fluxes
> Database, ICOS, JapanFlux, KoFlux, OzFlux, SAEON, and TERN. These products also include
> a modified version of ERA5 hourly data provided by the Copernicus Climate Change
> Service.

## Processing references

- AmeriFlux BASE: Chu, H., Christianson, D.S., Cheah, YW. et al. AmeriFlux BASE data
  pipeline to support network growth and data sharing. *Sci Data* 10, 614 (2023).
  https://doi.org/10.1038/s41597-023-02531-2[^chu-2023]
- AmeriFlux FLUXNET and FLUXNET2015: Pastorello, G. et al. The FLUXNET2015 dataset and
  the ONEFlux processing pipeline for eddy covariance data. *Sci Data* 7, 225 (2020).
  https://doi.org/10.1038/s41597-020-0534-3[^pastorello-2020]

## Data availability statement

If your paper has a data availability section, the AmeriFlux policy suggests:

> The AmeriFlux [DATA PRODUCT] were accessed from [SOURCE] on XX Month YYYY

where [SOURCE] can be the AmeriFlux data portal, AmeriFlux APIs, the FLUXNET User
Interface for the Shuttle, or the FLUXNET Shuttle code. Data downloaded through
ameriflux-mcp came through the AmeriFlux APIs.

## What each policy asks of you

| Policy | Obligations |
| --- | --- |
| AmeriFlux CC-BY-4.0 | Cite each site's DOI; include the DOE acknowledgment; add the data availability sentence when the paper has that section; informing data providers about publications is recommended. |
| AmeriFlux Legacy | Contact the site PIs when you start in-depth analysis (they may offer co-authorship); cite each DOI; acknowledge site funding; include the DOE "data portal" acknowledgment; inform providers before publication; use the AmeriFlux logo or link in presentations. |
| FLUXNET2015 Tier 1 | CC-BY-4.0: cite Pastorello et al. (2020); list each site by its FLUXNET ID and/or DOI; informing data providers is recommended. |
| FLUXNET2015 Tier 2 | Scientific and educational use; contact the data providers when you begin research that could lead to a publication; give them at least three weeks to contribute after the first draft; list each site in a table. Six sites are Tier 2 only (RU-Sam, RU-SkP, RU-Tks, RU-Vrk, SE-St1, ZA-Kru) and are not part of Pastorello et al. (2020). |

**Mixing escalates.** A study that combines CC-BY-4.0 and Legacy AmeriFlux data follows
the Legacy policy for all of it; one that combines FLUXNET2015 Tier 1 and Tier 2 data
treats all of it as Tier 2. `amf_get_citation` reports the effective policy for the
sites you name, with each obligation marked required or recommended, and
[Citations and BADM](../tools/citation.md) describes everything it returns.

## Citing ameriflux-mcp

ameriflux-mcp is software, not a data source: cite the data as above. If you want to
mention the tool, for example in a methods section:

> Data were discovered and retrieved with ameriflux-mcp (idss-mesa, University of New
> Mexico; https://github.com/idss-mesa/ameriflux-mcp), version X.Y.Z.

[^amf-policy]: AmeriFlux Data Policy. <https://ameriflux.lbl.gov/data/data-policy/>
[^fluxnet-policy]: FLUXNET Data Policy. <https://fluxnet.org/data/data-policy/>
[^chu-2023]: Chu et al. (2023), Sci Data 10, 614. <https://doi.org/10.1038/s41597-023-02531-2>
[^pastorello-2020]: Pastorello et al. (2020), Sci Data 7, 225. <https://doi.org/10.1038/s41597-020-0534-3>

---8<--- https://idss-mesa.github.io/ameriflux-mcp/about/license/

---
title: "License"
description: "ameriflux-mcp code is MIT-licensed by the Regents of the University of New Mexico; these docs are CC-BY 4.0; flux data carry their own policies."
type: Policy
tags:
  - about
  - license
  - MIT
  - CC-BY
generated:
  by: "claude/opus-5.5"
  at: "2026-10-23T00:00:00Z"
sources:
  - id: ameriflux-mcp-license
    resource: "https://github.com/idss-mesa/ameriflux-mcp/blob/main/LICENSE"
    title: "ameriflux-mcp LICENSE file (MIT)"
    author: "team:idss-mesa"
  - id: mit
    resource: "https://opensource.org/license/mit"
    title: "The MIT License"
    author: "team:opensource-org"
  - id: cc-by-4
    resource: "https://creativecommons.org/licenses/by/4.0/"
    title: "Creative Commons Attribution 4.0 International (CC BY 4.0)"
    author: "team:creativecommons"
  - id: amf-policy
    resource: "https://ameriflux.lbl.gov/data/data-policy/"
    title: "AmeriFlux Data Policy"
    author: "team:ameriflux"
status: stable
---

# License

Three things meet on this site: the server software, the documentation you are reading,
and the AmeriFlux and FLUXNET data the server gives access to. Each has its own terms.

## Server code — MIT

The ameriflux-mcp source code (the `ameriflux_mcp` Python package, the `ameriflux-mcp`
command-line program, tests and build scripts) is released under the
[MIT License](https://opensource.org/license/mit){target=_blank}[^mit]:

> Copyright (c) 2026 The Regents of the University of New Mexico

The full text is in the repository's
[`LICENSE`](https://github.com/idss-mesa/ameriflux-mcp/blob/main/LICENSE){target=_blank}
file[^ameriflux-mcp-license]. In short: you may use, copy, modify, merge, publish,
distribute, sublicense and sell the software, provided the copyright notice and
permission notice are included; the software is provided "as is", without warranty.
Code and data that ameriflux-mcp ports from other projects (amerifluxr, the FLUXNET
Shuttle, ONEFlux) keep their own BSD-style licenses and are credited in the repository's
[`NOTICE`](https://github.com/idss-mesa/ameriflux-mcp/blob/main/NOTICE){target=_blank}
file.

## Documentation text — CC-BY 4.0

The prose, tables and examples on this site (everything under `docs/` in the repository,
including the OKF frontmatter) are licensed under
[Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/){target=_blank}[^cc-by-4].
You may share and adapt the material for any purpose, provided you give appropriate
credit ("ameriflux-mcp documentation, idss-mesa / The Regents of the University of New
Mexico, CC-BY 4.0") and indicate whether changes were made. Code snippets embedded in the
documentation may alternatively be used under the MIT terms above. Quoted data-policy
text belongs to AmeriFlux and FLUXNET.

## Flux data — per site and product

Data retrieved through ameriflux-mcp are not part of this project and are not covered by
either license above. Each AmeriFlux site shares its data under the CC-BY-4.0 license or
the AmeriFlux Legacy policy, and FLUXNET2015 under Tier 1 (CC-BY-4.0) or Tier 2[^amf-policy].
Follow the policy of every site you use, and cite it as described in
[Citing AmeriFlux and FLUXNET data](citing-ameriflux.md).

## Trademarks and affiliation

ameriflux-mcp is an independent project of
[idss-mesa](https://github.com/idss-mesa){target=_blank} at the University of New
Mexico. It is not developed, endorsed or supported by the AmeriFlux Management Project,
Lawrence Berkeley National Laboratory, FLUXNET or the U.S. Department of Energy. Their
names belong to their respective owners; this site uses its own original artwork.

[^mit]: The MIT License. <https://opensource.org/license/mit>
[^ameriflux-mcp-license]: ameriflux-mcp `LICENSE` file. <https://github.com/idss-mesa/ameriflux-mcp/blob/main/LICENSE>
[^cc-by-4]: Creative Commons Attribution 4.0 International. <https://creativecommons.org/licenses/by/4.0/>
[^amf-policy]: AmeriFlux Data Policy. <https://ameriflux.lbl.gov/data/data-policy/>

---8<--- https://idss-mesa.github.io/ameriflux-mcp/log/

# Directory Update Log

## 2026-10-24
* **Update**: downloads are off by default until AmeriFlux answers — [Downloads](tools/downloads.md), [Download identity](getting-started/identity.md), [Configuration](getting-started/configuration.md) (`--downloads`), [Install](getting-started/install.md) and [Quickstart](getting-started/quickstart.md).
* **Creation**: [Prompts, resources and status](tools/prompts-and-resources.md) — the three prompts (build step 8), every guide and reference resource, the site template and `amf_ping`; [Sync downloads to CyVerse](getting-started/sync-cyverse.md), ported from neon-mcp with the download-in-progress check.
* **Update**: v0.1.0 — [home](index.md), [Install](getting-started/install.md) (Docker ships; PyPI from the v0.1.0 tag), [Quickstart](getting-started/quickstart.md), [For AI agents](about/ai-agents.md), [Configuration](getting-started/configuration.md) and [Roadmap](tools/roadmap.md) (all eight steps done); [Downloads](tools/downloads.md) links the CyVerse sync.
* **Creation**: [Downloads](tools/downloads.md) — `amf_download_data` (build step 7): products, the plan and its disclosure, the consent call and its checks, the transfer and integrity checks, what is written to disk.
* **Update**: [Download identity](getting-started/identity.md) — the tool now exists; the `?=<user ID>` tag is stripped and nothing written holds the identity; [Tool reference](tools/reference.md) regenerated (12 tools); [Roadmap](tools/roadmap.md) — step 7 done; [home](index.md), [Install](getting-started/install.md) and [Quickstart](getting-started/quickstart.md) — what works today.
* **Creation**: [Local files](tools/local-files.md) — `amf_list_files`, `amf_preview_data` and `amf_read_bif` (build step 6): local roots, file families, summaries, rows, QC filters, UTC offsets, the SUBSET view, BIF privacy and the archive safety rules.
* **Update**: [Tool reference](tools/reference.md) regenerated (11 tools); [Roadmap](tools/roadmap.md) — step 6 done; [home](index.md), [Install](getting-started/install.md) and [Quickstart](getting-started/quickstart.md) — what works today.
* **Creation**: [Variables](tools/variables.md) — `amf_search_variables` and `amf_describe_variables` (build step 5): the BASE and FLUXNET grammars, units and QC per resolution, the dictionaries, heights and coverage at a site.
* **Creation**: [Citations and BADM](tools/citation.md) — `amf_get_citation` (versioned citations, effective policy, verbatim acknowledgments, site funding, BibTeX) and `amf_get_badm`.
* **Update**: [Citing AmeriFlux and FLUXNET data](about/citing-ameriflux.md) — the FLUXNET2015 citation form and the FLUXNET2015 obligations as the policy page words them; [Tool reference](tools/reference.md) regenerated (8 tools); [Roadmap](tools/roadmap.md) — step 5 done; [home](index.md), [Install](getting-started/install.md) and [Quickstart](getting-started/quickstart.md) — what works today.
* **Creation**: [Discovery and availability](tools/discovery.md) — `amf_search_sites`, `amf_get_site` and `amf_get_availability` (build step 4), site naming, policy labelling, empty sites and verdicts, the Köppen caveat, and the reference resources.
* **Update**: [Tool reference](tools/reference.md) regenerated (4 tools); [Roadmap](tools/roadmap.md) — step 4 done; [home](index.md), [Install](getting-started/install.md) and [Quickstart](getting-started/quickstart.md) — what works today.

## 2026-10-23
* **Update**: [Tool reference](tools/reference.md) — `amf_ping` reports cache statistics (build step 3); [Roadmap](tools/roadmap.md) — step 3 done.
* **Creation**: [Tool reference](tools/reference.md), generated from the tool registry by `scripts/gen_tools_reference.py` (`amf_ping`).
* **Update**: [Configuration](getting-started/configuration.md) — the settings table is now generated from `config.py` by `scripts/gen_config_reference.py` (59 settings); value-free validation errors and the look-alike variables are documented.
* **Update**: [Install](getting-started/install.md), [home](index.md), [Quickstart](getting-started/quickstart.md), [Roadmap](tools/roadmap.md) and [For AI agents](about/ai-agents.md) — the server now starts and answers `amf_ping`; real `--check` output; troubleshooting for invalid configuration.
* **Creation**: Documentation site on Zensical (OKF v0.2), ported from edi-mcp and modelled on gbif-mcp's: home page, the `zensical.toml` configuration, the OKF validator, the `llms.txt` generator and the post-build agent surface (Markdown mirror, `okf:*` head metadata, `robots.txt`).
* **Creation**: [Install ameriflux-mcp](getting-started/install.md) for macOS, Linux and Windows: uv, git and access to the private repository, the `scripts/install.sh` installer (six agents, `--with-identity`, refuses to register a server that does not start), manual registration, Docker, verification, troubleshooting, upgrades and removal.
* **Creation**: [Quickstart](getting-started/quickstart.md), [Download identity](getting-started/identity.md), [Clients](getting-started/clients.md) and [Configuration](getting-started/configuration.md) (planned settings until build step 2 generates the table).
* **Creation**: [Roadmap](tools/roadmap.md) of the twelve planned tools and eight build steps.
* **Creation**: [For AI agents](about/ai-agents.md), [Citing AmeriFlux and FLUXNET data](about/citing-ameriflux.md) and [License](about/license.md).

## 2026-10-22
* **Creation**: Started the ameriflux-mcp documentation bundle (OKF v0.2) with this log.