usa-npn-mcp-server
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., "@usa-npn-mcp-server get magnitude phenometrics for aspen in Colorado 2022"
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.
National Phenology Network MCP Server

Available MCP Tools
export-raw-data- Exports raw data to JSON or JSONL files in allowed directories.get-raw-data- Fetches raw data instead of summaries as from other tools. Limited to 300 records with truncation message if exceeded.individual-phenometrics- Fetches individual phenometrics (summarized data).magnitude-phenometrics- Fetches magnitude phenometrics (magnitude data).mapping- Maps site phenometrics onto a map of the USA with optional color labeling.observation-comment- Fetches observation comments based on observation_id.query-literature- Queries database of structured summaries from 175 papers that use phenology and phenometrics data.query-reference-material- Queries database containing NPN API reference material using a generated SQL query.site-phenometrics- Fetches site phenometrics (site-level data).status-intensity- Fetches status and intensity data (raw observation data). Use sparingly (can return massive datasets), prioritize phenometrics tools.
Available MCP Resources
recent-queries- List of recent query hash IDs and metadata for cached data access.available-roots- List of available root directories for file export operations.
Available MCP Prompts
map-data- Generate a map of the data using the NPN API.
🧑🏿💻 Developing
Prerequisites
uv will manage the virtual environment and dependencies for you.
Install uv for your operating system:
curl -LsSf https://astral.sh/uv/install.sh | shIn powershell, run:
# Install uv
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Clone the repository
Using HTTPS (recommended for most users):
git clone https://github.com/VectorInstitute/usa-npn-mcp-server.gitUsing SSH (if you have SSH keys configured with GitHub):
git clone git@github.com:VectorInstitute/usa-npn-mcp-server.gitAfter cloning with either method:
cd usa-npn-mcp-serverInstalling dependencies
After uv is installed, run:
uv sync
source .venv/bin/activateIn powershell, run:
uv sync
. .\.venv\Scripts\activate.ps1If the last command returns an error about running scripts being disabled on the system, you can run the following command in PowerShell to allow script execution for the current user:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUserThen run the activation command again:
. .\.venv\Scripts\activate.ps1These commands set up and activate the .venv environment as specified in the pyproject.toml and uv.lock files.
Related MCP server: usgswater
Configuration
Configure for Claude Desktop App
You can download the Claude Desktop Application from here.
Once installed, you will need to modify your claude_desktop_config.json to make it aware of the MCP Server.
How to find and modify claude_desktop_config.json:
Open Claude Desktop app
Click on "Claude" in the menu bar and select "Settings"
In the Settings window, click on the "Developer" tab in the left sidebar
Click the "Edit Config" button
This will open a Finder window showing the location of the
claude_desktop_config.jsonfileOpen the file with your preferred text editor
{
"mcpServers": {
"npn": {
"command": "bash",
"args": [
"-c",
"source /absolute/path/to/usa-npn-mcp-server/.venv/bin/activate && uv run usa_npn_mcp_server /absolute/path/to/export/directory"
]
}
}
} NOTE: Replace /absolute/path/to/usa-npn-mcp-server/ with local path to repo dir and /absolute/path/to/export/directory with local path to directory where you want exported files to be saved (or exclude this part to disable file export). You can specify multiple directories separated by spaces. For more info, see File Export Configuration.
Open Claude Desktop app
CTRL+Comma or Open the menu bar (three bar symbol top-left) and select "File" and "Settings"
In the Settings window, click on the "Developer" tab in the left sidebar
Click the "Edit Config" button
This will open a window showing the location of the
claude_desktop_config.jsonfileOpen the file with your preferred text editor.
{
"mcpServers": {
"npn": {
"command": "cmd.exe",
"args": [
"/c",
"C:\\absolute\\path\\to\\usa-npn-mcp-server\\.venv\\Scripts\\activate.bat && uv run usa_npn_mcp_server C:\\absolute\\path\\to\\export\\directory"
]
}
}
} NOTE: Replace C:\\absolute\\path\\to\\usa-npn-mcp-server\\ with local path to repo dir and C:\\absolute\\path\\to\\export\\directory with local path to directory where you want exported files to be saved (or exclude this part to disable file export). You can specify multiple directories separated by spaces - be sure to use backslashes for Windows paths. For paths containing spaces and more details, see File Export Configuration.
After saving the changes, restart Claude Desktop. If you receive no error messages from the Claude UI, the USA-NPN MCP server is likely installed correctly. Clicking the two buttons in the bottom left of the new chat box should reveal new options with npn labeling.

You should see a new local MCP server in the "Connectors" section of the Settings as below. This example has Filesystem and npn (usa-npn-mcp-server) MCP Servers enabled.

To enable tool use, you can click "Configure" (seen in the image above) and adjust which tools are enabled using the blue sliders and the permissions for each tool.

If you do not configure permissions this way, the tools will be enabled by default and permissions will be set to "Always ask permission" and each tool use will ask with an in-chat pop-up as below.

Recommended Complementary MCP Servers
Additional MCP Servers can be added to Claude Desktop in Settings using the Extensions tab by clicking Browse extensions. For use together with the USA-NPN MCP Server, the two following MCP Servers are recommended:
1. Filesystem:
Let Claude access specified directories in your filesystem to read and write files.
Configure
filesystemwith matching allowed directories asusa-npn-mcp-serverfor making data available during data analysis - both from recent queries saved to file and for externally sourced data files.
Note: A more fully featured alternative is Desktop Commander but it is not available in the listed extensions and would need to be configured by clicking add a custom one and performing custom installation and configuration. However, adding advanced or too many different MCP Servers to Claude can bloat your context window with tool descriptions. If you are experiencing context limitations, consider disabling some or all additional MCP Servers.
2. Context7:
Let Claude access up-to-date code documentation for data analysis.
File Export Configuration
The server supports exporting data to files within specified directories. You can configure allowed export directories in two ways:
Command-line Arguments (Recommended)
Pass directory paths as arguments when starting the server:
# Single directory
uv run usa_npn_mcp_server /path/to/exports
# Multiple directories
uv run usa_npn_mcp_server /path/to/exports /path/to/another/dirEnvironment Variable
Set the NPN_MCP_ALLOWED_DIRS environment variable:
# Unix/macOS (colon-separated)
export NPN_MCP_ALLOWED_DIRS="/path/to/exports:/path/to/another/dir"
# Windows (semicolon-separated)
set NPN_MCP_ALLOWED_DIRS="C:\path\to\exports;D:\another\dir"Windows Paths with Spaces (Escaped Quotes Method)
For paths containing spaces, wrap each path with escaped double quotes (\"):
{
"mcpServers": {
"npn": {
"command": "cmd.exe",
"args": [
"/c",
"\\"C:\\\\Users\\\\John Doe\\\\Documents\\\\usa-npn-mcp-server\\\\.venv\\\\Scripts\\\\activate.bat\\" && uv run usa_npn_mcp_server \\"C:\\\\Program Files\\\\Data Export\\""
]
}
}
}Multiple Windows Paths with Spaces
Quote each path individually when specifying multiple directories:
{
"mcpServers": {
"npn": {
"command": "cmd.exe",
"args": [
"/c",
"\\"C:\\\\Company Software\\\\NPN Tools\\\\usa-npn-mcp-server\\\\.venv\\\\Scripts\\\\activate.bat\\" && uv run usa_npn_mcp_server \\"D:\\\\Shared Data\\\\Research Projects\\" \\"E:\\\\Export Results\\\\Team Analysis\\""
]
}
}
}Security Note: The server will only allow file operations within the specified directories for security.
Debugging
Debugging with MCP Inspector (Currently only macOS and Linux): To run a locally hosted MCP interpreter for debugging, use:
# Without file export
npx @modelcontextprotocol/inspector uv run usa_npn_mcp_server
# With file export to a specific directory
npx @modelcontextprotocol/inspector uv run usa_npn_mcp_server /path/to/exportsThe first time you run this command you'll be prompted to download @modelcontextprotocol/inspector.
This command starts the MCP inspector within the uv-managed environment. The inspector can be used locally in-browser to inspect/test the server.
Testing dependencies: To install dependencies for testing (codestyle, unit tests, integration tests), run:
uv sync --devOther MCP Servers
For examples of other MCP servers and implementation patterns, see: https://github.com/modelcontextprotocol/servers
Available Tools
10 toolsexport-raw-dataA
Export cached raw data to JSON or JSONL file. Requires MCP client to provide roots (allowed directories) for file operations.
Inputs: hash_id (required), file_format (required), filename, output_path.
get-raw-dataA
Retrieve raw data from cache using hash ID. Limited to 300 records with truncation message if exceeded. Use 'recent-queries' resource to see available hash IDs.
Inputs: hash_id (required).
individual-phenometricsA
About the tool: Provides start and end dates of phenological activity for individual plants and animal species, derived from status data. Each record represents one 'phenological episode' - a period of continuous activity for a specific phenophase on an individual organism (like when one specific maple tree's leaves went from bud break to full leaf drop).
When to use: To understand phenological patterns within species, analyze individual plant behavior, study variation between organisms of the same species, or investigate multiple episodes of activity within a single growing season.
Key applications:
Studying phenological diversity within populations
Analyzing individual plant responses to local microclimates
Documenting multiple flowering/leafing episodes in water-limited ecosystems
Understanding species-specific phenological strategies
Quality control for site-level aggregations
Research on plant physiological responses to environmental triggers
Important considerations:
For plants: Shows actual start/end dates for individual organisms
For animals: Shows presence/absence periods at species level (since individual animals aren't tracked)
Requires date range specification (typically calendar year)
Multiple episodes may occur for same individual/phenophase within one season (e.g., after frost damage or drought recovery)
Essential for understanding the biological basis of site-level patterns
Data interpretation: Records show individual_id, phenophase onset/end dates, and episode duration. -9999 values indicate missing data.
Inputs: start_date (required), end_date (required), bottom_left_x1, bottom_left_y1, +13 more.
magnitude-phenometricsA
About the tool: Summarizes the intensity and abundance of phenological activity across multiple individuals, sites, or time periods using aggregated status and intensity data. Shows 'how much' phenological activity is occurring (not just when), providing insights into the magnitude, synchrony, and temporal patterns of biological processes.
When to use: Understanding broad ecological patterns, studying synchrony between interacting species, analyzing peak activity timing, or investigating how environmental changes affect the intensity of biological processes across populations.
Key applications:
Species synchrony analysis: Quantifying how synchronized phenological timing is between interacting species (pollinators and plants, herbivores and host plants, predators and prey)
Peak activity timing: Identifying when maximum biological activity occurs across populations
Climate change impacts: Studying how warming affects the magnitude and timing of phenological events
Biodiversity patterns: Understanding temporal overlap in species activity within ecosystems
Population-level responses: Analyzing how abundant or widespread phenological activity is across landscapes
Conservation planning: Identifying critical timing windows for species management
Scientific context: Based on current research showing that phenological synchrony between species is shifting due to climate change, with implications for ecosystem functioning and species interactions. This tool helps quantify these critical ecological relationships.
Requires: Date range and frequency parameters (daily, weekly, etc.) are essential. Recommended to specify species and phenophases of interest to avoid overwhelming results. Research applications:
'Are migrating birds arriving when their insect food sources are most abundant?'
'How synchronous is flowering across plant species in prairie communities?'
'Has climate change affected the temporal overlap between butterfly emergence and host plant activity?'
Data interpretation: Results show time-series data of phenological abundance/intensity aggregated by specified frequency. Values represent proportion of 'yes' records, animal abundance measures, or intensity metrics across the selected populations.
Inputs: start_date (required), end_date (required), frequency (required), bottom_left_x1, +13 more.
mappingC
Construct a map from results of a previous Site Phenometrics query to the NPN API, using longitude, latitude and specified variables to plot onto map of USA.
Inputs: tool_name (required), plot_type (required), title (required), color_by.
observation-commentA
Retrieve the comment for a given observation (from getObservationComment endpoint), results store as readable Resource 'observation_comment'
Inputs: observation_id (required).
query-literatureC
Query an SQL database for structured summaries of studies that used data collected by National Phenology Network. The tables have the following structure:
Table: literature, Length: 175, Headers: ['Title', 'Authors', 'DOI', 'DOI link', 'Venue', 'Citation count', 'Year', 'Filename', 'Measured variables', 'Temporal Range', 'Spatial Scope', 'Data Filtering', 'Statistical Tests', 'Modelling', 'Software Tools', 'Limitations', 'Main findings', 'Research gaps', 'Future research', 'Independent variables', 'Dependent variables', 'Organism', 'Summary of discussion', 'API Query', "Supporting quotes for 'Measured variables'", "Supporting tables for 'Measured variables'", "Reasoning for 'Measured variables'", "Supporting quotes for 'Temporal Range'", "Supporting tables for 'Temporal Range'", "Reasoning for 'Temporal Range'", "Supporting quotes for 'Spatial Scope'", "Supporting tables for 'Spatial Scope'", "Reasoning for 'Spatial Scope'", "Supporting quotes for 'Data Filtering'", "Supporting tables for 'Data Filtering'", "Reasoning for 'Data Filtering'", "Supporting quotes for 'Statistical Tests'", "Supporting tables for 'Statistical Tests'", "Reasoning for 'Statistical Tests'", "Supporting quotes for 'Modelling'", "Supporting tables for 'Modelling'", "Reasoning for 'Modelling'", "Supporting quotes for 'Software Tools'", "Supporting tables for 'Software Tools'", "Reasoning for 'Software Tools'", "Supporting quotes for 'Limitations'", "Supporting tables for 'Limitations'", "Reasoning for 'Limitations'", "Supporting quotes for 'Main findings'", "Supporting tables for 'Main findings'", "Reasoning for 'Main findings'", "Supporting quotes for 'Research gaps'", "Supporting tables for 'Research gaps'", "Reasoning for 'Research gaps'", "Supporting quotes for 'Future research'", "Supporting tables for 'Future research'", "Reasoning for 'Future research'", "Supporting quotes for 'Independent variables'", "Supporting tables for 'Independent variables'", "Reasoning for 'Independent variables'", "Supporting quotes for 'Dependent variables'", "Supporting tables for 'Dependent variables'", "Reasoning for 'Dependent variables'", "Supporting quotes for 'Organism'", "Supporting tables for 'Organism'", "Reasoning for 'Organism'", "Supporting quotes for 'Summary of discussion'", "Supporting tables for 'Summary of discussion'", "Reasoning for 'Summary of discussion'", "Supporting quotes for 'API Query'", "Supporting tables for 'API Query'", "Reasoning for 'API Query'"]
Description: Contains structured summaries of 175 papers that use phenology and phenometrics, included in the table is the reasoning and sourcing for each summary column.
Inputs: sql_query (required).
query-reference-materialB
Query an SQL database for reference material that can be used to translate natural language into specific ids and terms needed for querying the NPN API with other tools. There is no need to query the 'datasets' table unless specific observer groups are mentioned. The Tables have the following structure:
Table: species, Length: 1940, Headers: ['species_id', 'common_name', 'genus', 'genus_id', 'genus_common_name', 'species', 'kingdom', 'itis_taxonomic_sn', 'functional_type', 'class_id', 'class_common_name', 'class_name', 'order_id', 'order_common_name', 'order_name', 'family_id', 'family_name', 'family_common_name', 'species_type']
Description: Contains info on species
Table: phenophases, Length: 400, Headers: ['definition_id', 'phenophase_id', 'phenophase_name', 'definition', 'start_date', 'end_date', 'dataset_id', 'comments']
Description: Contains info on phenophases
Table: phenoclasses, Length: 230, Headers: ['phenophase_id', 'phenophase_description', 'definition_ids', 'phenophase_names']
Description: Contains info on phenoclasses (a grouping of phenophases)
Table: datasets, Length: 14, Headers: ['dataset_id', 'dataset_name', 'dataset_description', 'dataset_comments', 'dataset_documentation_url']
Description: Contains info on datasets and their contributors
Table: networks, Length: 924, Headers: ['network_id', 'network_name']
Description: Contains info on observation groups or networks (aka partner groups)
Inputs: sql_query (required).
site-phenometricsA
About the tool: Aggregates individual phenological data to provide average start and end dates of phenological activity for each species at each monitoring site. Represents the 'typical' timing for a species at a location by averaging across all individuals of that species at the site.
When to use: Creating phenological calendars, analyzing site-specific timing patterns, comparing phenology across locations, understanding regional growing seasons, or studying how local climate affects species timing.
Key applications:
Phenological calendars: Creating seasonal timing guides for specific locations
Growing season analysis: Quantifying length of active growing periods for sites/regions
Climate relationship studies: Investigating how phenological timing relates to temperature, precipitation, and seasonal patterns
Site comparisons: Comparing phenological timing across elevation gradients, latitude gradients, or different habitat types
Regional management: Planning for activities like controlled burns, invasive species management, or ecotourism
Agricultural applications: Understanding wild plant timing to inform crop management decisions
Scientific context: Site phenometrics average out individual variation to reveal location-specific phenological signatures. Essential for understanding how climate drivers affect species timing at landscape scales.
Research applications:
'When do oak leaves typically emerge at Yellowstone vs. Great Smoky Mountains?'
'How long is the typical growing season for maple species in Minnesota?'
'When should we expect peak wildflower blooms in different Colorado elevation zones?'
Data interpretation: Each record represents one species at one site for the specified time period. Start/end dates are averages across individuals. Sites represent uniform habitat areas ≤15 acres. Values of -9999 represent missing/null data.
Inputs: start_date (required), end_date (required), bottom_left_x1, bottom_left_y1, +13 more.
status-intensityA
About the tool: Retrieves raw, unprocessed observation records from citizen and professional scientists documenting day-by-day phenological status (yes/no) and intensity measurements for individual plants and animal species. Each record represents a single observation event showing whether specific phenophases (like 'breaking leaf buds' or 'full bloom') were occurring on a particular date for a specific individual organism at a monitoring site.
When to use: Only for detailed analysis of specific observation events, quality control, or when you need the granular day-to-day data that underlies the aggregated metrics. Most users should use Individual, Site, or Magnitude Phenometrics instead.
Key applications: Data validation, understanding observer reporting patterns, analyzing day-to-day phenological transitions, custom aggregations not available in other tools. Performance warning: This tool can return massive datasets (potentially millions of records). Always limit queries to small date ranges (≤30 days recommended) and specific geographic areas or species to prevent system crashes. Use aggregated tools (Individual/Site/Magnitude Phenometrics) for broader analyses.
Data interpretation: Values of -9999 represent missing/null data. Records include observation date, individual ID, phenophase status, intensity measurements, and site metadata.
Inputs: start_date (required), end_date (required), bottom_left_x1, bottom_left_y1, +12 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a clearly distinct purpose: raw data handling (export/get), individual, site, and magnitude phenometrics, mapping, observation comments, literature and reference queries, and raw status records. There is no overlap or ambiguity among the tool descriptions.
Tool names consistently use lowercase, hyphen-separated words (e.g., 'export-raw-data', 'individual-phenometrics', 'query-literature'). While not strictly verb_noun, the pattern is uniform and descriptive, with only 'mapping' deviating slightly as a single word.
With 10 tools, the server is well-scoped for its domain. Each tool addresses a specific aspect of phenology data access and analysis, covering raw data, aggregated metrics, literature, and reference material without unnecessary duplication.
The tool set provides comprehensive coverage for the National Phenology Network data: raw observation retrieval, multiple levels of phenometric aggregation, metadata queries, literature search, and mapping. No major gaps are apparent for typical use cases.
Maintenance
Related MCP Connectors
Query real-time and historical USGS water data from ~8,000 stream gages and groundwater wells.
Search NOAA climate stations and datasets, fetch historical weather observations.
USGS Water MCP — wraps USGS National Water Information System (NWIS) REST services (free, no auth)
Query NASA POWER solar, wind, building, and agroclimatology data.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables querying USGS water data including real-time and historical streamflow, gage height, and water temperature from USGS gauges across the United States.3MIT
- AlicenseNot gradedqualityFmaintenanceWraps USGS NWIS REST services to query water data such as streamflow, groundwater levels, and water quality.6 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables querying recent bird observations from the eBird citizen-science database by location.119 npmMIT
- AlicenseAqualityBmaintenanceEnables AI agents to discover NEON ecological data products and sites, check data availability, list and download data files, and generate citations via the NEON Data API.20MIT