Copernicus Earth Observation MCP Server

A comprehensive Model Context Protocol (MCP) server for accessing Copernicus Earth Observation data from the Copernicus Data Space ecosystem. This server provides a complete suite of tools for searching, downloading, and managing satellite imagery from all Copernicus Sentinel missions.

📋 Table of Contents

• Features

• Available Missions

• Quick Start

• Running the Server

• Available Tools

• Complete Workflow Example

• Configuration

• Testing

• Architecture

• Authentication Model

• Error Handling

• Performance Considerations

• Security Notes

• Troubleshooting

• Contributing

• License

• Acknowledgments

🌟 Features

Search & Discovery

• Multi-Mission Support: Access data from Sentinel-1, Sentinel-2, Sentinel-3, Sentinel-5P, and Sentinel-6 missions

• Advanced Search: Search by location (point, polygon, bounding box), date range, cloud cover, and mission-specific parameters

• Coverage Analysis: Analyze temporal coverage and availability of satellite data for specific regions

• Recent Images: Get the most recent satellite images for monitoring and change detection

• Comprehensive Metadata: Retrieve detailed image metadata including acquisition details, processing levels, and technical specifications

Download & Data Management

• Image Download: Download full products, quicklook previews, and compressed versions of satellite images

• Batch Operations: Download multiple images concurrently with configurable concurrency limits

• Intelligent Selection: Automatic best-image selection based on recency, cloud cover, and processing level

• Availability Checking: Verify download availability and get file size information before downloading

• Download Links: Get all available download URLs for any satellite image

File Management

• File Listing: List and analyze downloaded files with filtering by type, size, and date

• Statistics: Get comprehensive statistics about downloaded files (by mission, file type, time period)

• Automated Cleanup: Clean up old or large downloads with age-based and size-based strategies

• Dry Run Mode: Safety-first approach with preview of cleanup actions before execution

🛰️ Available Missions

🚀 Quick Start

Prerequisites

• Python 3.11 or higher

• pip package manager

• Copernicus Data Space account (free registration required)

Installation

1. Clone the repository:

   git clone <repository-url> cd copernicus-mcp

2. Install dependencies:

   pip install -r requirements.txt

3. Install in development mode:

   pip install -e .

4. Set up authentication:

   # Linux/Mac export COPERNICUS_USERNAME="your-email@example.com" export COPERNICUS_PASSWORD="your-password" # Windows (Command Prompt) set COPERNICUS_USERNAME=your-email@example.com set COPERNICUS_PASSWORD=your-password # Windows (PowerShell) $env:COPERNICUS_USERNAME="your-email@example.com" $env:COPERNICUS_PASSWORD="your-password"

   Register for free at: https://dataspace.copernicus.eu/

Authentication Test

Verify your credentials work:

📡 Running the Server

Basic Usage

Command Line Options

MCP Client Integration

Add to your MCP client configuration (e.g., Claude Desktop, Zed):

🛠️ Available Tools

Search & Discovery Tools

1. search_copernicus_images

Search for satellite images from Copernicus missions.

Parameters:

• geometry: GeoJSON polygon coordinates, point [lon, lat], or bbox [min_lon, min_lat, max_lon, max_lat]

• geometry_type: 'point', 'polygon', or 'bbox'

• mission: Mission name ('sentinel-1', 'sentinel-2', 'sentinel-3', 'sentinel-5p', 'sentinel-6')

• start_date, end_date: Date range (YYYY-MM-DD)

• max_cloud_cover: Maximum cloud cover percentage (0-100, optical missions only)

• max_results: Maximum number of results (1-1000)

Example:

2. get_image_details

Get comprehensive metadata for a specific satellite image.

Parameters:

• image_id: Satellite image ID (from search results)

• mission: Optional mission name

Returns: Detailed metadata including download URLs, processing level, cloud cover, footprint, and authentication guidance.

3. get_mission_info

Get detailed information about Copernicus satellite missions.

Parameters:

• mission: Optional specific mission name

Returns: Mission capabilities, sensors, applications, resolution, and revisit time.

4. get_recent_images

Get the most recent satellite images for a region.

Parameters:

• geometry: Location coordinates

• geometry_type: 'point', 'polygon', or 'bbox'

• mission: Mission name

• days_back: Number of days to look back (default: 7)

• max_results: Maximum results (default: 10)

5. check_coverage

Analyze satellite image coverage for a region over time.

Parameters:

• geometry: Location coordinates

• geometry_type: 'point', 'polygon', or 'bbox'

• mission: Mission name

• start_date, end_date: Analysis period

• group_by: Group results by 'day', 'week', 'month', or 'year'

Download Tools

6. download_image

Download a Copernicus satellite image by ID.

Parameters:

• image_id: Image ID from search results (required)

• mission: Mission name (default: 'sentinel-2')

• download_type: 'full', 'quicklook', or 'compressed' (default: 'full')

• output_dir: Custom output directory (default: 'downloads')

Example:

7. batch_download_images

Download multiple images concurrently.

Parameters:

• image_ids: List of image IDs to download

• mission: Mission name (default: 'sentinel-2')

• download_type: 'full', 'quicklook', or 'compressed' (default: 'full')

• output_dir: Output directory (default: 'batch_downloads')

• max_concurrent: Maximum concurrent downloads (default: 3)

Example:

8. search_and_download

Search for images and automatically download the best match.

Parameters:

• geometry: Location coordinates

• geometry_type: 'point', 'polygon', or 'bbox' (default: 'point')

• mission: Mission name (default: 'sentinel-2')

• start_date, end_date: Search date range

• max_cloud_cover: Maximum cloud cover percentage

• download_type: 'full', 'quicklook', or 'compressed' (default: 'quicklook')

• output_dir: Output directory

• limit: Maximum search results to consider (default: 5)

Example:

9. check_download_availability

Check if images are available for download.

Parameters:

• image_ids: List of image IDs to check

Returns: Availability status, file sizes, and quicklook availability for each image.

10. get_product_download_links

Get all available download links for an image.

Parameters:

• image_id: Image ID

Returns: All download URLs (full, compressed, quicklooks) with metadata.

File Management Tools

11. list_downloaded_files

List downloaded satellite image files.

Parameters:

• download_dir: Directory to scan (default: 'downloads')

• file_type: Filter by 'full', 'quicklook', 'compressed', or None for all

• limit: Maximum files to return (default: 50)

Example:

12. cleanup_downloads

Clean up downloaded files based on criteria.

Parameters:

• download_dir: Directory to clean (default: 'downloads')

• older_than_days: Remove files older than X days

• max_size_mb: Keep total size under X MB (removes oldest first)

• file_type: Filter by file type

• dry_run: Only show what would be deleted (default: True)

Example:

13. get_download_statistics

Get statistics about downloaded files.

Parameters:

• download_dir: Directory to analyze (default: 'downloads')

Returns: Comprehensive statistics including total files, size, breakdown by mission/file type/month, and oldest/newest files.

📊 Complete Workflow Example

🔧 Configuration

Environment Variables

Default Directories

• Downloads: downloads/ (individual downloads)

• Batch Downloads: batch_downloads/ (batch operations)

• Search Results: search_downloads/ (search_and_download)

Performance Settings

• Max Concurrent Downloads: 3 (configurable in batch_download_images)

• API Timeout: 60 seconds

• Download Chunk Size: 8KB

• Token Cache: 4 minutes (with 1-minute buffer)

🧪 Testing

Test Scripts

Example Scripts

🏗️ Architecture

Server Structure

Key Components

1. Authentication Manager: Handles token acquisition, caching, and refresh

2. Search Engine: Advanced query builder for Copernicus Data Space API

3. Download Manager: Concurrent downloads with progress tracking

4. File Manager: Disk space management and cleanup

5. MCP Interface: FastMCP-based tool registration and protocol handling

🔒 Authentication Model

Public Access (No Authentication Required)

• Mission information

• Basic search operations

• Metadata retrieval

Authenticated Access (Credentials Required)

• Image downloads (full, quicklook, compressed)

• Batch downloads

• Availability checks

• Download link retrieval

Token Management

• Automatic token acquisition from Copernicus Identity Service

• Token caching with expiration handling

• Graceful error handling for invalid credentials

• Support for both environment variables and parameter-based authentication

⚠️ Error Handling

The server includes comprehensive error handling for:

Authentication Errors

• Missing credentials

• Invalid credentials

• Token expiration

• Rate limiting

API Errors

• Invalid image IDs

• Unavailable products

• Network timeouts

• API quota exceeded

File System Errors

• Insufficient disk space

• Permission denied

• Invalid file paths

• Corrupted downloads

User Input Errors

• Invalid geometry formats

• Unsupported mission parameters

• Date range errors

• Invalid download types

📈 Performance Considerations

Download Sizes

• Quicklooks: 100KB - 1MB (recommended for testing)

• Compressed Products: 100MB - 1GB

• Full Products: 1GB - 10GB+ (varies by mission)

Network Usage

• Start with quicklook downloads for testing

• Use max_concurrent to control bandwidth usage

• Monitor disk space for large downloads

API Limits

• Respect Copernicus Data Space API rate limits

• Use appropriate date ranges and geographic extents

• Cache search results when possible

🚨 Security Notes

Credential Safety

• Never hardcode credentials in code

• Use environment variables or secure credential stores

• Tokens are automatically refreshed and never stored permanently

• All authentication errors are logged without exposing sensitive information

Network Security

• All API calls use HTTPS with proper certificate validation

• Download URLs are validated before use

• Timeout settings prevent hanging connections

File Security

• Downloaded files use standard file permissions

• No automatic execution of downloaded content

• Cleanup operations require explicit confirmation (dry-run mode by default)

🔧 Troubleshooting

Common Issues and Solutions

Authentication Failures

Download Failures

1. Check disk space: Ensure you have sufficient space for downloads

2. Verify image ID: Use valid IDs from search results

3. Try quicklook first: Test with smaller files before downloading full products

4. Check network: Ensure stable internet connection

Search Issues

1. Date range: Use reasonable date ranges (e.g., last 30 days)

2. Geometry size: Keep search areas manageable

3. Cloud cover: Adjust cloud cover filters for optical missions

Debug Mode

Enable debug logging for detailed information:

Log Files

• Check application logs for detailed error messages

• Monitor download progress in real-time

• Review cleanup operations before execution

🙏 Acknowledgments

Data Providers

• European Space Agency (ESA) for the Copernicus program

• Copernicus Data Space Ecosystem for providing API access

• European Commission for funding and support

Technical Dependencies

• FastMCP framework for MCP server implementation

• httpx for async HTTP client functionality

• pydantic for data validation and serialization

• shapely for geometric operations

📚 Additional Resources

Documentation

• Copernicus Data Space Documentation

• MCP Protocol Specification

• FastMCP Documentation

Tutorials and Examples

• Complete workflow examples in example_download_usage.py

• Test scripts for different scenarios

• Configuration examples in mcp_config.json

🚀 Roadmap

Planned Features

• Advanced filtering: More granular search parameters

• Visualization tools: Image preview and analysis

• Batch processing: Automated workflows for large datasets

• Integration plugins: Support for GIS software and data analysis tools

Performance Improvements

• Caching layer: Reduce API calls for repeated searches

• Parallel processing: Optimize batch operations

• Progress reporting: Enhanced download status updates

Community Features

• Template workflows: Pre-configured analysis pipelines

• Plugin system: Extensible architecture for custom tools

• Collaboration tools: Shared datasets and analysis results

Note: This server is actively maintained. For the latest updates, check the GitHub repository and release notes.

Happy Earth Observation! 🌍🛰️