neon-mcp
A token-aware MCP server that lets AI agents discover, inspect, download, and cite NEON ecological data across products, sites, locations, releases, samples, taxonomy, documents, and prototype datasets.
Search and inspect NEON data products and field sites, including per-site/month/release availability and provisional data.
List and download NEON data files, package ZIPs, prototype files, or documents (stdio only; token needed for data/prototype downloads), with size caps, MD5 checks, and skip/error handling.
Explore location hierarchies and details: coordinates, UTM, elevation, properties, history, polygons, parent chains, and paged children.
Browse NEON releases, get per-product DOIs, and generate NEON-format citations and BibTeX, including provisional and prototype datasets.
Search taxonomy and sample classes; retrieve sample custody chains and relatives (sample views require a token).
Search prototype datasets, fetch metadata/files, and retrieve NEON document metadata or extracted PDF text.
Run guarded read-only GraphQL queries against NEON metadata for gaps not covered by dedicated tools.
Check server health, token status, downloads, cache, rate-limit headroom, and optionally test NEON API reachability.
Use paginated, schema-validated, token-aware results over stdio or stateless HTTP
/mcp, with caching and rate-limit awareness.
Provides a read-only GraphQL tool for querying NEON's public metadata endpoint, enabling allow-listed GraphQL queries for metadata not covered by dedicated tools, with depth limits and result pruning.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@neon-mcp find NEON breeding bird data at Harvard Forest"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
neon-mcp
A Model Context Protocol server for the NEON Data API — the National Ecological Observatory Network's 200 data products at 81 field sites. It lets AI agents find products and sites, check which months have data (released and provisional), list and download data files, walk location hierarchies, browse releases, taxonomy, samples and prototype datasets, and cite what they use — through compact, paginated, schema-validated tool results instead of NEON's multi-megabyte payloads.
MCP 2026-07-28 stateless core on the Python
mcp2.x SDK; stdio (both protocol eras) and stateless Streamable HTTP at/mcp.20 tools, 8
neon://resources + 3 templates, 3 prompts.Token-aware: discovery works anonymously; data files and sample views use your NEON API token (required by NEON since June 2026), never logged or echoed.
Rate-limit and size aware: per-identity throttling under NEON's limits, caching, GraphQL-first catalogs, a 50 KB result budget with explicit paging.
Documentation: https://idss-mesa.github.io/neon-mcp/ (also as llms.txt and llms-full.txt for agents).
Quick start
uv tool install git+https://github.com/idss-mesa/neon-mcp # PyPI release pending
neon-mcp --check # {"ok": true, ...}
claude mcp add neon -s user -e NEON_TOKEN="$NEON_TOKEN" -- neon-mcp --transport stdioThen ask your agent to call neon_ping, or to "find NEON breeding bird data at
Harvard Forest for June 2023 and cite it".
Related MCP server: io.github.krnzt/ecoscope
NEON API token
Optional. Without a token everything works except neon_list_files,
neon_download_files (for data and prototype files) and neon_get_sample, which
return auth_required, and neon_get_prototype_dataset, which leaves out a
prototype dataset's files. To create one:
Sign in at https://data.neonscience.org (a free account: Google, CILogon or email).
Open My Account (https://data.neonscience.org/myaccount), click GET API TOKEN at the bottom, then Copy.
Put it in the server's environment as
NEON_TOKEN, the name NEON's own tutorials use (NEON_MCP_NEON__API_TOKENoverrides it;NEON_API_TOKENis not read).Run
neon-mcp --checkand look for"tokenAccepted": true.
Hosted deployments accept each caller's token in the X-API-Token header behind
HTTPS. Never commit a token. Details:
NEON API token.
Clients
Client | Registration |
Claude Code |
|
Claude Code (hosted) |
|
Codex CLI |
|
Claude Desktop, OpenCode, Antigravity | JSON snippets in Clients |
Tools
Family | Tools |
Products and sites |
|
Availability and data |
|
Locations |
|
Releases and citation |
|
Taxonomy, samples, prototype |
|
Utilities |
|
Inputs, result fields and endpoints: tool reference (generated from the registry).
Configuration and deployment
YAML (--config), NEON_MCP_<SECTION>__<FIELD> environment variables and flags; see
Configuration,
config.yaml.example and .env.example. For a hosted server:
neon-mcp --transport http behind TLS, or the included Dockerfile — see
Hosted HTTP deployment.
Development
git clone https://github.com/idss-mesa/neon-mcp && cd neon-mcp
uv sync --all-extras
uv run pytest && uv run mypy --strict src && uv run ruff check src tests scriptsSee CLAUDE.md, AGENTS.md (documentation rules) and
Contributing.
Citing NEON data and license
NEON data are CC BY 4.0; cite each product at its release DOI (neon_get_citation does
this) — see Citing NEON data.
neon-mcp is MIT-licensed, Copyright (c) 2026 The Regents of the University of New Mexico,
and is not affiliated with NEON, Battelle or NSF.
Available Tools
20 toolsneon_download_filesDownload NEON filesAIdempotent
Download data files (or package ZIPs), a prototype dataset's files, or a NEON document into the configured download directory (stdio only; data files need a token). The plan is checked against file/byte caps before any transfer; MD5s are verified; identical existing files are skipped. Next: read the CSVs (pandas.read_csv) and cite with neon_get_citation.
Inputs: hor, tmi, ver, kind, +16 more. Returns: files, notes, source, totals, +4 more
neon_find_locationsFind NEON locationsARead-onlyIdempotent
Locations under a site, domain, REALM or named location, filtered by locationType (towers, huts, megapits, soil plots, observation plots, ...) or text, with coordinates and optional proximity. REALM and domain walks need location_type; site walks without it report typesAvailable. Next: call neon_get_location for one location's detail.
Inputs: root, limit, query, offset, +7 more. Returns: page, items, notes, roots, +6 more
neon_get_availabilityGet NEON data availabilityARead-onlyIdempotent
Which sites and months have data for a product (one row per site), which products have data at a site (one row per product), or one product-site cell; month ranges per release including PROVISIONAL, optionally windowed and filtered. Works without a token and is small (GraphQL). Next: call neon_list_files for a product, site and month range.
Inputs: site, limit, format, offset, +8 more. Returns: mode, page, rows, notes, +12 more
neon_get_citationCite NEON dataARead-onlyIdempotent
NEON-format citation text and BibTeX for a data product in a release (DOI, default the newest release with a DOI), for provisional data (no DOI; archive what you used), or for a prototype dataset. Wording follows NEON's data policy (CC BY 4.0). Next: include the citation with any results; read neon://guide/citing-neon-data for the rules.
Inputs: format, product, release, site_codes, +3 more. Returns: doi, notes, bibtex, doiUrl, +12 more
neon_get_documentGet a NEON documentARead-onlyIdempotent
Metadata of a NEON document (ATBD, protocol, user guide) by spec number or documents URL: type, size, file name, description and the products that reference it; optionally its text, extracted in memory and paged by character offset. No token. Next: page through text with char_offset, or call neon_download_files(spec_number=...) on stdio.
Inputs: url, pages, product, max_chars, +3 more. Returns: url, size, text, notes, +14 more
neon_get_locationGet a NEON locationARead-onlyIdempotent
One named location in depth: coordinates, UTM, elevation, orientation and offsets, properties, active periods; optionally its parent chain, location history, polygon and paged children (pruned by location_type). Names are case-sensitive. Next: call neon_find_locations to list locations of a type under it.
Inputs: name (required), include, location_type, children_limit, +2 more. Returns: notes, source, xOffset, yOffset, +34 more
neon_get_productGet a NEON data productARead-onlyIdempotent
One data product: codes, name, team, status, themes, keywords, releases with DOIs and an availability summary; opt-in include[] sections add abstract and design text, packages, specs (ATBDs, protocols), change logs (paged), per-site availability rows and biorepository collections. Accepts a code or a name. Next: call neon_get_availability or neon_get_citation for the product.
Inputs: product (required), include, release, text_budget, +4 more. Returns: urls, notes, specs, source, +33 more
neon_get_prototype_datasetGet a NEON prototype datasetARead-onlyIdempotent
One prototype dataset: title, abstract, years, version, DOI, themes, teams, sites, and by default its files with sizes, MD5s and signed URLs; optional project/design/metadata descriptions, publication citations and related products. Next: call neon_download_files(prototype_uuid=...) on stdio, or neon_get_citation(prototype_uuid=...).
Inputs: uuid (required), include, files_limit, text_budget, +2 more. Returns: doi, uuid, files, notes, +29 more
neon_get_releaseGet a NEON data releaseARead-onlyIdempotent
One release (tag, uuid or 'latest'): its data products with DOIs (paged, filterable), optionally its sites and manifest artifacts, or one product/site exactly as published in that release. Unknown tags fail with the list of valid releases. Next: call neon_get_citation for a product in the release.
Inputs: release (required), include, site_code, product_code, +4 more. Returns: site, uuid, notes, sites, +10 more
neon_get_sampleGet a NEON sampleARead-onlyIdempotent
A physical sample's custody chain (NEON API token required): identifiers, events with their field values, parents and children; degree=N adds relatives N steps away. Identify it by tag (+class), UUID, barcode or archive GUID; an ambiguous tag asks which class (MRTR) or lists candidates. Next: follow parent or child identifiers with another neon_get_sample call.
Inputs: limit, degree, fields, offset, +7 more. Returns: page, items, notes, degree, +4 more
neon_get_siteGet a NEON field siteARead-onlyIdempotent
One field site: name, type, state, domain, coordinates, DEIMS id, and (by default) every data product available there with month ranges and provisional counts; optional releases, full description and location record (elevation, UTM, properties). Next: call neon_get_availability or neon_list_files for a product at this site.
Inputs: site (required), include, release, products_limit, +2 more. Returns: urls, notes, source, deimsId, +18 more
neon_graphqlRun a NEON GraphQL queryARead-onlyIdempotent
Read-only GraphQL against NEON's public metadata endpoint for shapes the other tools do not cover. Guard rails: queries only, allow-listed root fields, depth <= 8, one __type/__schema, results pruned to max_bytes with truncatedPaths. No token is sent. Prefer the dedicated tools for products, sites and availability. Next: read neon://reference/graphql-schema for types.
Inputs: query, max_bytes, variables, operation_name, +1 more. Returns: data, notes, errors, source, +6 more
neon_list_filesList NEON data filesARead-onlyIdempotent
Data files for a product at sites over months (NEON API token required): names, kinds, tables, HOR/VER/TMI, sizes, MD5s and signed URLs (~7 days), plus package ZIP links for a single site-month. detail='summary' or 'site_months' sizes a pull without listing files. Next: call neon_download_files with the same selectors (stdio), or use the URLs.
Inputs: product (required), site_codes (required), start_month (required), hor, +14 more. Returns: page, files, notes, detail, +16 more
neon_list_releasesList NEON data releasesARead-onlyIdempotent
All NEON data releases (RELEASE-2021 ... RELEASE-2026 today), newest first, with generation dates, product counts and manifest artifacts. Releases are immutable and carry per-product DOIs; newer data are PROVISIONAL. Next: call neon_get_release for one release's products and DOIs.
Inputs: include_artifact_urls. Returns: page, items, notes, source, +3 more
neon_list_sample_classesList NEON sample classesARead-onlyIdempotent
NEON's supported sample classes (e.g. bet_IDandpinning_in.individualID) with descriptions, filterable by text, or the classes one sample tag belongs to. No token. Next: call neon_get_sample with a tag and class, a sample UUID, a barcode or an archive GUID.
Inputs: limit, query, offset, sample_tag. Returns: page, items, notes, source, +4 more
neon_pingCheck neon-mcp statusARead-onlyIdempotent
Liveness and capability report: server version and protocol, whether a NEON API token is available (it unlocks data files and sample views), whether downloads are enabled, catalog warmth, cache and rate-limit headroom. With check_api=true it makes one ~1 KB NEON request. Never reveals the token. Next: call neon_search_products to find a data product.
Inputs: check_api. Returns: api, pong, cache, notes, +14 more
neon_search_productsSearch NEON data productsARead-onlyIdempotent
Find NEON data products by keywords, theme, science team, level, status, site, domain or date coverage; ranked results with facets and each product's site count and month range. Served from a cached catalog (no token). A bare code such as DP1.10003.001 matches exactly. Next: call neon_get_availability with a productCode, or neon_get_product for detail.
Inputs: site, sort, level, limit, +10 more. Returns: page, items, notes, facets, +6 more
neon_search_prototype_datasetsSearch NEON prototype datasetsARead-onlyIdempotent
Search NEON's prototype datasets (early or experimental data outside the standard products) by text, theme, science team, site, years, file type or publication flag, with facets. Each has its own DOI and version. No token. Next: call neon_get_prototype_dataset with a uuid for files.
Inputs: limit, query, theme, offset, +6 more. Returns: page, items, notes, facets, +3 more
neon_search_sitesSearch NEON field sitesARead-onlyIdempotent
Find NEON's 81 field sites by code, name, state, domain, site type, product availability or proximity (latitude/longitude + radius_km, nearest first); optional elevation and UTM. Cached catalog, no token. Next: call neon_get_site or neon_get_availability(site=...) for a siteCode.
Inputs: limit, query, offset, product, +8 more. Returns: page, items, notes, facets, +6 more
neon_search_taxonomySearch NEON taxonomyARead-onlyIdempotent
NEON's taxonomy lists, paged: every taxon of a type (BIRD, PLANT, SMALL_MAMMAL, ...) or taxa by rank (kingdom ... genus) or exact scientific name with a genus fallback. Rows keep NEON's Darwin Core keys (dwc:scientificName, dwc:vernacularName, ...). No token. Next: follow page.nextOffset, or call neon_search_products for data about the taxa.
Inputs: genus, limit, order, class_, +9 more. Returns: page, items, notes, source, +4 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Each tool has a clear, distinct purpose: searching sites, products, availability, files, locations, samples, taxonomy, and prototypes are all separated. Even similar tools like get_site vs get_product or list_files vs download_files are unambiguous due to clear nouns and descriptions.
All tools follow a consistent neon_<verb>_<noun> pattern, with verbs like get, list, search, download, find, ping, and graphql. The naming is uniformly snake_case and predictable, making it easy to guess tool behaviors.
With 20 tools, the server covers a broad domain (NEON ecological data) and each tool addresses a specific need, but the count is at the upper edge of the ideal range. Some tools like neon_graphql and neon_ping add flexibility but could be considered optional; still, the count is justifiable for the extensive API surface.
The server provides comprehensive coverage: search and discovery (sites, products, samples, prototypes, taxonomy), metadata retrieval (get_site, get_product, get_release, get_location, get_document), availability and citation, file listing and downloading, plus a GraphQL fallback for edge cases. It covers the full lifecycle from discovery to data access and citation, with no obvious gaps.
Maintenance
Related MCP Connectors
Access Pollinations models and API capabilities through agent tools.
Connect AI clients to biomedical data and tools.
660+ data tools for agents: TikTok, Douyin, Instagram, YouTube, X, weather, GitHub. Pay per call.
Real-world data for agents: air quality, geocoding, quakes, holidays, web search
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides AI agents with structured access to the U.S. EIA Open Data API for energy data including power plants, operations, fuel prices, projections, and state CO2 emissions.MIT
- AlicenseNot gradedqualityDmaintenanceEnables MCP agents to discover, import, query, visualize, select, and cite NEON and local scientific datasets while keeping credentials, private paths, and bulk data out of model context.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to access NOAA's national climate archive—GHCN-Daily observations, station search, and dataset catalog—without an API key.76 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to search Earth-science dataset collections by keyword, platform, instrument, time range, or bounding box; fetch full collection metadata; and list individual data granules with direct download links.81 npmMIT