essdeepdive

name: essdeepdive description: Query the ESS-DeepDive fusion database for fields and file metadata, and generate citations for linked ESS-DIVE datasets via MCP tools.

Setup (once)

Run the MCP server locally:

uv run python src/essdive_mcp/main.py --token YOUR_ESS_DIVE_TOKEN_HERE

Or provide the token via a file:

uv run python src/essdive_mcp/main.py --token-file /path/to/token.txt

Note: the environment variable name is ESSDIVE_API_TOKEN (no underscore between ESS and DIVE).

Register with Claude Code (stdio transport):

claude mcp add --transport stdio essdive-mcp --env ESSDIVE_API_TOKEN=YOUR_ESS_DIVE_TOKEN_HERE -- uv run python ./src/essdive_mcp/main.py

Token file alternative:

claude mcp add --transport stdio essdive-mcp -- uv run python ./src/essdive_mcp/main.py --token-file /path/to/token.txt

Tools

• search-ess-deepdive
• get-ess-deepdive-dataset
• get-ess-deepdive-file
• generate-data-citation
• lookup-project-portal
• coords-to-map-links

Usage examples

Search for fields named "temperature" with at least 100 records:

search-ess-deepdive with field_name="temperature" and record_count_min=100

Filter by DOI and field definition text:

search-ess-deepdive with doi="10.15485/2453885" and field_definition="soil" and page_size=25

Get detailed field metadata for a dataset file:

get-ess-deepdive-dataset with doi="10.15485/2453885" and file_path="dataset.zip/data.csv"

Get full file metadata and download info:

get-ess-deepdive-file with doi="doi:10.15485/2453885" and file_path="dataset.zip/data.csv"

Generate a citation for a dataset DOI found in ESS-DeepDive results:

generate-data-citation with id="doi:10.15485/2453885" and access_date="2026-05-06"

Generate citations for several linked ESS-DIVE dataset DOIs in one call:

generate-data-citation with ids=["doi:10.15485/2453885", "doi:10.15485/3014404"] and access_date="2026-05-06"

Look up a project acronym and its portal details:

lookup-project-portal with query="CHESS"

Create map links for a point (geojson.io + Google Maps + Google Earth KML):

coords-to-map-links with points=[[38.9219, -106.9490]] and zoom=12

Notes

• row_start is 1-based. Use max_pages for automatic pagination.
• doi may be provided as 10.xxxx/... or doi:10.xxxx/....
• When a user asks for citable sources, report dataset-level citations with generate-data-citation using the DOI from ESS-DeepDive results.
• Use ids on generate-data-citation when citing multiple linked ESS-DIVE dataset DOIs from ESS-DeepDive results.
• Do not cite individual ESS-DeepDive field records as if they were standalone datasets; cite the linked ESS-DIVE dataset DOI.
• For project names, acronyms, aliases, Mule IDs, and URLs, consult ../references/essdive_projects.yaml. It combines curated portal entries with projects imported from the ESS-DIVE Mule project registry.