EEA GeoNetwork MCP Server

A Model Context Protocol (MCP) server that provides tools to interact with the European Environment Agency (EEA) GeoNetwork Catalogue API (GeoNetwork 4.4.9).

Features

This MCP server provides 20 tools for interacting with the EEA GeoNetwork Catalogue:

Search & Discovery

• search_records - Search for metadata records with full Elasticsearch query support
• search_by_extent - Find records by geographic bounding box
• get_record - Retrieve detailed metadata for a specific record by UUID
• get_record_by_id - Retrieve a record by its internal numeric ID
• get_related_records - Find related records (parent, children, services, datasets)

Data Export & Management

• get_record_formatters - List available export formats for a record
• export_record - Export metadata in various formats (XML, PDF, etc.)
• duplicate_record - Duplicate an existing metadata record (requires authentication)

Record Editing (Requires Authentication)

• update_record - Update any field using XPath (supports ISO 19139 and ISO 19115-3)
• update_record_title - Simplified tool to update a record's title (auto-detects schema)
• add_record_tags - Add tags/categories to a record
• delete_record_tags - Remove tags/categories from a record

Resource/Attachment Management

• upload_file_to_record - Upload a file from local filesystem directly to a metadata record (requires authentication)
• get_attachments - List all attachments/resources for a metadata record
• delete_attachment - Delete a specific attachment from a record (requires authentication)

Catalogue Information

• get_site_info - Get catalogue configuration and site information
• get_sources - List catalogue sources and sub-portals
• list_groups - List all user groups
• get_tags - Get available tags/categories
• get_regions - Get geographic regions/extents

Installation

Option 1: Docker (Recommended)

The easiest way to run the server is using Docker:

# Build and start the container
docker-compose up -d

# Check logs
docker-compose logs -f

# Stop the container
docker-compose down

The server will be available at http://localhost:3001

Environment Variables: You can customize the configuration by creating a .env file or editing the docker-compose.yml:

environment:
  - PORT=3001
  - BASE_URL=https://galliwasp.eea.europa.eu/catalogue/srv/api
  - CATALOGUE_USERNAME=your_username
  - CATALOGUE_PASSWORD=your_password

Option 2: Manual Installation

1. Install dependencies:

npm install

2. Build the project:

npm run build

3. (Optional) Configure environment variables:

# Create a .env file in the project root
PORT=3001
BASE_URL=https://galliwasp.eea.europa.eu/catalogue/srv/api
MAX_SEARCH_RESULTS=20

# Authentication for write operations (duplicate, update)
CATALOGUE_USERNAME=your_username
CATALOGUE_PASSWORD='your_password'

# Rate limiting
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

Note: For passwords containing special characters ($, #, etc.), wrap the value in single quotes.

Usage

Streamable HTTP Server (MCP Transport)

The server uses the official MCP Streamable HTTP transport with Server-Sent Events (SSE).

Start the server:

npm start

The server will start on port 3001 (or the port specified in the PORT environment variable).

Available endpoints:

• GET http://localhost:3001/health - Health check endpoint
• GET http://localhost:3001/info - Server information
• POST http://localhost:3001/upload - Upload file to basket (multipart/form-data)
• GET http://localhost:3001/uploads/:filename - Retrieve uploaded file
• POST http://localhost:3001/ - MCP message endpoint (standard JSON-RPC)
• GET http://localhost:3001/ - MCP SSE stream endpoint (for server-initiated messages)

Testing the server:

# Check if server is running
curl http://localhost:3001/health

# Should return: {"status":"ok","service":"eea-geonetwork-mcp"}

# Upload a file to the basket
curl -X POST http://localhost:3001/upload -F "file=@myfile.pdf"

# Returns: {"success":true,"file":{"url":"http://localhost:3001/uploads/myfile-123456789.pdf",...}}

Upload Basket

The server includes a built-in upload basket for temporary file storage. This allows you to upload files first, then attach them to metadata records using the URL.

Swagger UI (Easiest Method):

1. Open http://localhost:3001/api-docs in your browser
2. Expand the "POST /upload" endpoint
3. Click "Try it out"
4. Select a file and click "Execute"
5. Copy the returned URL from the response
6. Use this URL with the upload_resource_from_url MCP tool

How it works:

1. Upload a file via POST /upload endpoint (or use Swagger UI)
2. Server stores the file in the uploads/ directory
3. Server returns a URL: http://localhost:3001/uploads/filename
4. Use this URL with upload_resource_from_url tool to attach to metadata records

Configuration:

# Optional environment variables
UPLOAD_DIR=./uploads           # Upload directory (default: ./uploads)
MAX_FILE_SIZE=104857600        # Max file size in bytes (default: 100MB)

Swagger UI:

• Access the interactive API documentation and file upload interface at:
• http://localhost:3001/api-docs

With Claude Desktop

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "eea-geonetwork": {
      "command": "node",
      "args": ["C:\\Users\\dubos\\_Projects\\EEA_sdi_mcp\\dist\\index.js"]
    }
  }
}

Example Queries

Once connected to Claude Desktop, you can ask questions like:

• "Search the EEA catalogue for datasets about air quality"
• "Find all metadata records within the bounding box of Europe"
• "Get detailed information about record UUID abc-123-def"
• "Export this metadata record as XML"
• "What geographic regions are available in the catalogue?"
• "Show me all datasets related to this parent record"

API Base URL

The server connects to: https://galliwasp.eea.europa.eu/catalogue/srv/api (Sandbox Environment)

Development

Commands

• Build: npm run build - Compile TypeScript to dist/
• Watch mode: npm run dev - Compile TypeScript in watch mode (auto-recompile on changes)
• Start: npm start - Run the compiled server

Development Workflow

For active development, run two commands in separate terminals:

Terminal 1 - Compile TypeScript in watch mode:

npm run dev

Terminal 2 - Start the server:

npm start

This way, TypeScript will automatically recompile when you make changes, and you can restart the server to pick up the new changes.

Architecture

The server uses the official MCP SDK with Streamable HTTP transport (stateless mode):

• Express server handles HTTP endpoints with CORS support
• MCP Server handles tool requests via Streamable HTTP/SSE
• Axios client communicates with the EEA GeoNetwork API (30s timeout)
• Modular design with separate files:
  • src/index.ts - Server setup and routing
  • src/tools.ts - Tool definitions (20 tools)
  • src/handlers.ts - Tool implementation handlers
  • src/types.ts - TypeScript interfaces

Tools Reference

search_records

Search for metadata records in the catalogue.

Parameters:

• query (string): Search text
• from (number): Starting position (default: 0)
• size (number): Number of results (default: 10, max: 100)
• bucket (string): Filter by facet bucket
• sortBy (string): Sort field
• sortOrder (string): "asc" or "desc"

get_record

Get detailed metadata for a specific record.

Parameters:

• uuid (string, required): Record UUID or ID
• approved (boolean): Only approved versions (default: true)

search_by_extent

Search records by geographic extent.

Parameters:

• minx (number, required): Minimum longitude (west)
• miny (number, required): Minimum latitude (south)
• maxx (number, required): Maximum longitude (east)
• maxy (number, required): Maximum latitude (north)
• relation (string): Spatial relationship - "intersects", "within", or "contains" (default: "intersects")

export_record

Export a metadata record in a specific format.

Parameters:

• uuid (string, required): Record UUID
• formatter (string, required): Format identifier (e.g., "xml", "pdf", "full_view")

Use get_record_formatters first to see available formats for a record.

duplicate_record

Duplicate an existing metadata record with a new UUID. Requires authentication.

Parameters:

• metadataUuid (string, required): UUID of the record to duplicate
• group (string, optional): Target group for the duplicated record
• isChildOfSource (boolean, optional): Set the source record as parent of the new record (default: false)
• targetUuid (string, optional): Specific UUID to use for the duplicated record (auto-generated if not provided)
• hasCategoryOfSource (boolean, optional): Copy categories from source record (default: true)

get_record_by_id

Retrieve a metadata record by its internal numeric ID. Useful for getting the UUID after a duplicate operation.

Parameters:

• id (number, required): Internal numeric ID of the record

update_record

Update a metadata record field using XPath. Requires authentication.

Parameters:

• uuid (string, required): UUID of the record to update
• xpath (string, required): XPath to the element to update
• value (string, required): New value (text for simple replacement, or full XML element)
• operation (string, optional): Operation type - "replace" (default), "add", or "delete"
• updateDateStamp (boolean, optional): Update the record's timestamp (default: true)

Common XPaths:

• ISO 19139 title: gmd:identificationInfo/*/gmd:citation/gmd:CI_Citation/gmd:title/gco:CharacterString
• ISO 19115-3 title: mdb:identificationInfo/*/mri:citation/cit:CI_Citation/cit:title/gco:CharacterString

update_record_title

Simplified tool to update a record's title. Automatically detects the schema (ISO 19139 or ISO 19115-3) and uses the correct XPath. Requires authentication.

Parameters:

• uuid (string, required): UUID of the record to update
• title (string, required): New title for the record

add_record_tags

Add tags (categories) to a metadata record. Requires authentication.

Parameters:

• uuid (string, required): UUID of the record
• tags (array of numbers, required): Array of tag IDs to add

Use get_tags first to find available tag IDs.

delete_record_tags

Remove tags (categories) from a metadata record. Requires authentication.

Parameters:

• uuid (string, required): UUID of the record
• tags (array of numbers, required): Array of tag IDs to remove

upload_file_to_record

Upload a file from your local filesystem directly to a metadata record as an attachment. The file is uploaded as binary data to GeoNetwork. Requires authentication.

Parameters:

• metadataUuid (string, required): UUID of the metadata record to attach the file to
• filePath (string, required): Absolute path to the local file (e.g., C:\Users\name\document.pdf or /home/user/document.pdf)
• visibility (string, optional): The sharing policy - "PUBLIC" or "PRIVATE" (default: PUBLIC)
• approved (boolean, optional): Use approved version or not (default: false)

Example:

metadataUuid: "43d7c186-2187-4bcd-8843-41e575a5ef56"
filePath: "C:\\Documents\\myfile.pdf"

Note: This tool directly uploads the file to GeoNetwork. The file must be accessible on the machine running the MCP server.

get_attachments

List all attachments/resources for a metadata record.

Parameters:

• metadataUuid (string, required): UUID of the metadata record
• sort (string, optional): Sort results by "type" or "name" (default: name)
• approved (boolean, optional): Use approved version or not (default: true)
• filter (string, optional): Filter pattern for attachment names (default: *)

Returns: Array of attachment objects with details like filename, type, URL, size, etc.

delete_attachment

Delete a specific attachment from a metadata record. Requires authentication.

Parameters:

• metadataUuid (string, required): UUID of the metadata record
• resourceId (string, required): The ID/filename of the resource to delete
• approved (boolean, optional): Use approved version or not (default: false)

Note: Use get_attachments first to find the exact resourceId of the attachment you want to delete.

License

MIT

Related Links

• EEA SDI Sandbox Catalogue
• API Documentation
• GeoNetwork Documentation
• Model Context Protocol