Oceanum MCP

An MCP server package that provides AI assistants with access to the Oceanum platform for ocean/environmental data and cloud storage.

Servers

This package contains multiple MCP servers, selectable at runtime:

Related MCP server: ERDDAP MCP Server

Prerequisites

Get an API token from oceanum.io. Set it as the DATAMESH_TOKEN environment variable.

Installation

pip install oceanum-mcp

Or run directly with uvx:

uvx oceanum-mcp              # combined server (default)
uvx oceanum-mcp datamesh     # datamesh only
uvx oceanum-mcp storage      # storage only
uvx oceanum-mcp --list       # show available servers

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Combined server (all tools):

{
  "mcpServers": {
    "oceanum": {
      "command": "uvx",
      "args": ["oceanum-mcp"],
      "env": {
        "DATAMESH_TOKEN": "your-token-here"
      }
    }
  }
}

Individual server (datamesh only):

{
  "mcpServers": {
    "oceanum-datamesh": {
      "command": "uvx",
      "args": ["oceanum-mcp", "datamesh"],
      "env": {
        "DATAMESH_TOKEN": "your-token-here"
      }
    }
  }
}

Claude Code

# Combined server
claude mcp add --transport stdio oceanum -- uvx oceanum-mcp

# Individual server
claude mcp add --transport stdio oceanum-datamesh -- uvx oceanum-mcp datamesh

Set the token in your environment:

export DATAMESH_TOKEN=your-token-here

VS Code / Cline / Continue

Use stdio transport with the same command:

{
  "command": "uvx",
  "args": ["oceanum-mcp"],
  "env": {
    "DATAMESH_TOKEN": "your-token-here"
  }
}

Environment Variables

Datamesh Tools

The intended workflow is: search_catalog → get_datasource_info → stage_query (dry run: learn the result size without downloading) → query_data for small results inline, or export_query to write large results to a file that analysis code reads directly.

search_catalog

Search the Datamesh catalog with optional text search, time range, and bounding box filters. Returns a JSON object with count and results; if count equals limit, more matches may exist.

get_datasource_info

Get full metadata for a datasource including schema, variables, coordinates, and attributes.

stage_query

Dry-run a query on the Datamesh gateway: reports the result size, container type, and domain length without downloading any data, echoes the canonical query, and recommends the next step (inline query vs export vs narrowing). Accepts the same query parameters as query_data.

query_data

Query a datasource with filters and return small results inline as coordinate-attributed JSON records with explicit truncated/lazy flags. The query is staged first: gridded results above the inline limit are summarized lazily (structure only); tabular results above the limit are refused with the staged size and alternatives. Library warnings (e.g. the 2,000,000-row cap on tabular queries) are included in the response.

export_query

Run a query and write the full result to a local file — the data-handle path for results too large to return inline. Gridded datasets stream lazily to NetCDF; tabular results write Parquet or CSV. Accepts the same query parameters as query_data plus:

load_datasource

Summarize an entire datasource. Gridded datasources are opened lazily (no data download); tabular datasources are downloaded only if under the inline size limit.

update_metadata

Update metadata on an existing datasource. Only provided fields are changed. Disabled when the server runs with OCEANUM_MCP_READ_ONLY set.

Storage Tools

list_files

List files and directories in Oceanum cloud storage.

file_exists

Check if a file or directory exists in storage.

read_file

Read the contents of a text file from storage.

write_file

Write text content to a file in storage.

delete_file

Delete a file or directory from storage.

file_info

Get metadata about a file or directory.

Example Workflows

Discover wave data in the Pacific:

1. search_catalog(search="wave", bbox=[120, -50, 180, 10])

2. get_datasource_info(datasource_id="some-wave-dataset")

3. stage_query(datasource_id="some-wave-dataset", variables=["Hs", "Tp"], time_start="2024-01-01", time_end="2024-01-31") to check the result size

4. query_data(...) with the same parameters if small, or export_query(..., path="waves.nc") if large

Shrink a 40-year hourly time series to something inline-sized:

1. stage_query(datasource_id="hindcast", variables=["Hs"], time_start="1984-01-01", time_end="2024-01-01") — too large

2. query_data(..., time_resolution="1MS", time_resample="mean") — monthly means, small enough to return inline

Browse and read files in cloud storage:

1. list_files(path="/") to see top-level contents

2. list_files(path="/my-project", recursive=True) to drill down

3. read_file(path="/my-project/config.json") to read a file

Get a quick summary of a dataset:

1. get_datasource_info(datasource_id="my-dataset") to see variables and time range

2. query_data(datasource_id="my-dataset", limit=10) to preview the data