nc-mcp

HanchaoLi/nc-mcp

3.2

If you are the rightful owner of nc-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

NetCDF Explorer MCP Server is a tool designed for exploring and analyzing netCDF files through a simple MCP server interface.

NetCDF Explorer MCP Server

A simple and powerful MCP (Message Communication Protocol) server for exploring, analyzing, and interacting with NetCDF format files. Designed to simplify NetCDF data management with intuitive APIs and efficient data handling.

Overview

NetCDF (Network Common Data Form) is a widely used format for storing scientific data. This MCP server provides a streamlined interface to work with NetCDF files, offering essential functionalities to list files, inspect structures, extract data, and analyze variables—all while handling large datasets efficiently through smart sampling.

Features

  • 📁 File Discovery: List all NetCDF files (.nc, .cdf, .netcdf, .nc4) in a specified directory.
  • 🔍 Structure Inspection: Retrieve detailed metadata of NetCDF files, including dimensions, variables, attributes, and global properties.
  • 📊 Data Extraction: Read variable data with support for flexible slicing (e.g., lat: "0:10:2" to extract subsets).
  • 🧠 Smart Sampling: Automatically sample large datasets to prevent memory overflow, with configurable element limits.
  • ⏰ Time Series Analysis: Extract temporal data from spatial variables, with optional custom location coordinates.
  • 🔎 Search Functionality: Find variables and attributes by keyword, simplifying navigation in complex files.
  • 📋 Variable Summaries: Generate human-readable summaries of variables, including dimensions, data types, and attributes.

Installation

Prerequisites

  • Python ≥ 3.13

Install via pip

pip install nc-mcp

Install from Source

  1. Clone the repository:

    git clone https://github.com/HanchaoLi/nc-mcp.git
cd nc-mcp

  2. Install dependencies (using uv for faster dependency management):

    # Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync dependencies
uv sync --all-groups

Quick Start

Start the Server

python -m nc_mcp_server.main

API Reference

Core Functions

FunctionDescriptionParameters
list_netcdf_filesLists all NetCDF files in a directory.directory (str): Path to search (default: .).
get_netcdf_infoReturns metadata and structure of a NetCDF file (dimensions, variables, attributes).file_path (str): Path to the NetCDF file.
get_variable_dataExtracts data from a specific variable (supports slicing and sampling).file_path (str), variable_name (str), slices (dict, optional), max_elements (int, default: 1000).
search_variablesSearches variables and attributes for a keyword (case-insensitive).file_path (str), search_term (str).
extract_timeseriesExtracts time series data from a spatial variable.file_path (str), variable_name (str), location (dict, optional: spatial coordinates like {"lat": 10, "lon": 20}).

Testing

Run the test suite to verify functionality:

uv run pytest tests/ -v

Tests cover:

  • File discovery logic
  • NetCDF structure parsing
  • Data extraction with slicing
  • Sampling for large datasets
  • Error handling for invalid inputs

License

This project is licensed under the MIT License. See the file for details.

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Links

Author

John Li