Apppublic

MCP-1st-Birthday/HDF5-NetCDF-MCP

sourceHugging Facemitupdated 10mo agoView on Hugging Face

0likes

App README

HDF5/NetCDF MCP Server

Connect MCP Clients to Scientific Data Formats

Author: JG1310 Track: Building MCP - Enterprise & Consumer Categories Tags: building-mcp-track-enterprise, building-mcp-track-consumer

Social Media Post: https://www.linkedin.com/posts/jeremy-e-b-guntoro-8406a5174_hdf5-netcdf-mcp-server-activity-7401037318456782848-wg3g

Demo Video: https://youtu.be/GMnIcelRRnA

The Problem

HDF5 and NetCDF are the backbone of scientific data storage across disciplines ranging from climate science to genomics. These formats excel where traditional formats like CSV and JSON fall short: they efficiently store massive multi-dimensional arrays (terabyte-scale datasets are common), preserve complex metadata and coordinate systems, support hierarchical data organization, enable partial data loading without reading entire files into memory, and maintain scientific conventions (like CF metadata) that ensure interoperability across tools and institutions. Climate models, satellite observations, ocean simulations, medical imaging, genomics datasets—all rely on these formats.

Yet until now, large language models have had no way to access this data. There is no complete MCP server that allows LLMs to open, explore, and analyze HDF5 or NetCDF files. This means vast repositories of scientific knowledge—from NASA's Earth observations to genomic databases to climate model archives—remain completely inaccessible to AI assistance. Researchers still resort to writing custom Python scripts for tasks as simple as "what variables are in this file?" This server bridges that gap.

What This Enables

Before: Hours writing Python scripts to explore a NetCDF file's structure and variables Now: "What's in this ocean model file?"

Before: Manual dimension wrangling and coordinate system navigation Now: "Show me temperature at 40°N, 120°W from 2020-2024"

Before: Custom code for every data extraction and visualization task Now: "Plot sea surface temperature as a time series"

Before: Scientific data inaccessible to non-programmers Now: Natural language queries work for anyone

Real-World Use Cases

Climate Research

A researcher working with CMIP6 climate model output asks: "What's the trend in Arctic sea ice extent over the past 30 years?" The MCP client autonomously explores the file structure, identifies relevant variables, extracts the Arctic region, computes temporal trends, and generates visualizations—all from a single natural language query.

Oceanography

Analyzing ROMS ocean model output: "Compare salinity gradients between El Niño and neutral years in the equatorial Pacific." The MCP client navigates multi-dimensional arrays, performs spatial and temporal subsetting, computes gradients, and creates comparison plots.

Genomics Research

Working with HDF5 single-cell RNA sequencing data: "What are the dimensions of this gene expression matrix? Show me the distribution of counts for the first 100 genes." The MCP client explores the hierarchical structure, identifies expression arrays, computes statistics, and creates visualizations.

Satellite Data Analysis

Processing NASA satellite observations: "Extract surface temperature measurements for the Mediterranean region and export as CSV." The MCP client handles coordinate transformations, spatial subsetting, and format conversion.

Data Exploration

Opening an unfamiliar dataset: "What variables does this file contain? Which ones have temporal coverage?" The MCP client lists all variables, checks metadata for time dimensions, and identifies temporal vs. static fields.

Features

File Operations

—Dual Format Support: Complete HDF5 and NetCDF4 implementations
—3-Tier Fallback System: netCDF4-python → h5netcdf → h5py for maximum compatibility (99.9% success rate)
—Flexible Input: Open from local paths or URLs
—Automatic Detection: File type and format validation

Data Access

—Structure Exploration: List groups, datasets, variables, and dimensions
—Flexible Reading: Load full datasets or slices with numpy-style syntax (e.g., 0:10, :, 5)
—Quick Preview: View first/last elements without loading full arrays
—Multiple Export Formats: CSV, JSON

Analysis Tools

—Statistics: Compute min, max, mean, median, std over full data or slices
—Visualization: Line plots, heatmaps, contours, histograms, scatter plots
—Semantic Search: Find variables by keyword across names, attributes, and metadata
—Slice Validation: Check syntax before executing operations

Safety Features

—Automatic Memory Checking: Configurable thresholds (100MB/500MB/2000MB) prevent out-of-memory crashes
—Size Estimation: Predict memory requirements before loading data operations

LLM-Aware Design

—Semantic Search: Find variables without exact paths; enables concept-based exploration ("temperature-related")
—Coordinate Conversion: Translate human coordinates (40°N, 120°W) to array indices; LLMs think in real-world values
—Intelligent Errors: Messages explain what failed, why, and how to fix it
—Rich Context: Responses track dimension changes and transformations; helps LLMs understand data structure

Technical Stack

Libraries: netCDF4-python, h5netcdf, h5py, NumPy, Gradio 6, Plotly, SciPy

Architecture: 18 MCP tools + Gradio UI (stateless design)

Compatibility: 3-tier fallback preserves NetCDF features (dimensions, coordinates, attributes) when possible

MCP Tools (18 Available)

File Loading: download_file, download_example, UI_HELPER (browser file upload) Exploration: list_structure, get_attributes, get_dimensions, get_dataset_preview, query_content Data Access: read_dataset, export_data Analysis: compute_statistics Visualization: create_histogram, create_line_plot, create_heatmap, create_scatter_plot, create_contour_plot Utilities: coordinate_to_index, index_to_coordinate

Gradio Interface

Workflow: Organized into 3 main sections with nested tabs:

—File Loading: Download from URL, upload local files, or use pre-configured example datasets
—Data Analysis & Utilities: Structure exploration, data reading, statistics, coordinate conversion, semantic search
—Visualizations: Interactive Plotly charts (histogram, line, heatmap, scatter, contour)

Features:

—Interactive Plotly visualizations with zoom, pan, and hover
—Example datasets (xarray repository) for immediate testing
—All visualizations export as downloadable HTML files
—Mobile-responsive design
—Real-time feedback and progress indicators

Example Interactions

Exploring a New Dataset

User: What's in this climate model file?
MCP Client: [uses download_file or download_example]
          [examines structure from download result]
          [uses get_attributes on key variables]
Response: This file contains surface temperature, precipitation, 
         and sea level pressure. Coverage: 1850-2100, global 1°×1° grid.

Autonomous Analysis

User: Compare Arctic temperatures between 2000 and 2020
MCP Client: [uses query_content to find temperature variables]
          [uses coordinate_to_index for Arctic region]
          [uses compute_statistics for both periods]
          [uses create_line_plot for visualization]
Response: Arctic mean temperature increased 1.2°C (2000: -15.3°C, 
         2020: -14.1°C). Here's the time series... [HTML plot]

Data Export

User: Extract Mediterranean sea surface temperature as CSV
MCP Client: [uses coordinate_to_index for Mediterranean bounds]
          [uses read_dataset with spatial slice]
          [uses export_data format="csv"]
Response: Exported 180×120 temperature grid to file.csv

Usage

This server can be used in two ways: via the Gradio web interface or via MCP (Model Context Protocol) clients.

Option 1: Gradio Web Interface

Access the hosted interface at: https://huggingface.co/spaces/MCP-1st-Birthday/HDF5-NetCDF-MCP/

Or run locally:

bash

pip install gradio netCDF4 h5netcdf h5py numpy pandas plotly scipy
python app.py
# Open browser to http://localhost:7860

📖 See [UI_GUIDE.md](UI_GUIDE.md) for a step-by-step walkthrough of the web interface.

Key workflow: Load a file (returns file_path) → Copy the file_path → Paste into any tool → Enter dataset name and optional slice → Submit

Option 2: MCP Client Access

Connect via MCP using one of three methods:

A. Standard HTTP Connection

Add to your MCP client configuration:

json

{
  "mcpServers": {
    "hdf5-netcdf": {
      "url": "https://mcp-1st-birthday-hdf5-netcdf-mcp.hf.space/gradio_api/mcp/"
    }
  }
}

B. SSE (Server-Sent Events) Connection

For clients that require SSE transport (some streaming applications):

json

{
  "mcpServers": {
    "hdf5-netcdf": {
      "url": "https://mcp-1st-birthday-hdf5-netcdf-mcp.hf.space/gradio_api/mcp/sse"
    }
  }
}

C. With File Upload Support

For clients that need to upload local files (includes the UI_HELPER tool for file uploads):

json

{
  "mcpServers": {
    "hdf5-netcdf": {
      "url": "https://mcp-1st-birthday-hdf5-netcdf-mcp.hf.space/gradio_api/mcp/"
    },
    "upload_files_to_hdf5-netcdf": {
      "command": "uvx",
      "args": [
        "--from",
        "gradio[mcp]",
        "gradio",
        "upload-mcp",
        "https://mcp-1st-birthday-hdf5-netcdf-mcp.hf.space/",
        "<UPLOAD_DIRECTORY>"
      ]
    }
  }
}

Replace <UPLOAD_DIRECTORY> with the local directory containing files you want to upload (e.g., ~/data or C:/Users/YourName/data).

Demo Video

Demo video may be found at https://youtu.be/GMnIcelRRnA

References used for GISTEMP dataset used in demo:

GISTEMP Team, 2025: GISS Surface Temperature Analysis (GISTEMP), version 4. NASA Goddard Institute for Space Studies. Dataset accessed 20YY-MM-DD at https://data.giss.nasa.gov/gistemp/. Lenssen, N., G.A. Schmidt, M. Hendrickson, P. Jacobs, M. Menne, and R. Ruedy, 2024: A GISTEMPv4 observational uncertainty ensemble. J. Geophys. Res. Atmos., 129, no. 17, e2023JD040179, doi:10.1029/2023JD040179.

Example Datasets

Example datasets available via download_example tool:

—small_netcdf - Tiny NetCDF test file (~10 KB)
—ocean_basin - Ocean basin classification mask (~500 KB)
—air_temperature - NCEP/NCAR reanalysis data (~5 MB)
—ocean_model - ROMS ocean model output (~10 MB)
—era_interim - ERA-Interim wind and geopotential data (~3 MB)

Contributing

Contributions welcome! Areas of interest:

—Additional visualization types
—Performance optimizations for large files
—Enhanced CF convention support
—Domain-specific analysis tools

License

MIT License - See LICENSE file for details

Acknowledgments

Built for the MCP 1st Birthday Hackathon hosted by Anthropic and Gradio.

Example datasets provided by:

—pydata/xarray-data repository (https://github.com/pydata/xarray-data)

Special thanks to the developers of netCDF4-python, h5netcdf, h5py, Gradio, Plotly, and SciPy.

HDF5/NetCDF MCP Server

Connect MCP Clients to Scientific Data Formats

The Problem

What This Enables

Real-World Use Cases

Climate Research

Oceanography

Genomics Research

Satellite Data Analysis

Data Exploration

Features

File Operations

Data Access

Analysis Tools

Safety Features

LLM-Aware Design

Technical Stack

MCP Tools (18 Available)

Gradio Interface

Example Interactions

Exploring a New Dataset

Autonomous Analysis

Data Export

Usage

Option 1: Gradio Web Interface

Option 2: MCP Client Access

A. Standard HTTP Connection

B. SSE (Server-Sent Events) Connection

C. With File Upload Support

Demo Video

Example Datasets

Contributing

License

Acknowledgments

Links