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.

🌟 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

🚀 Installation

Prerequisites

• Python 3.11 or higher
• pip package manager
• Copernicus Data Space account (free registration required)

📦 Steps

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"
   

   or in MCP Client...

   {
     "mcpServers": {
       "copernicus": {
         "command": "copernicus-mcp",
         "env": {
           "COPERNICUS_USERNAME": "your-email@example.com",
           "COPERNICUS_PASSWORD": "your-password"
         }
       }
     }
   }
   

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

Authentication Test

Verify your credentials work:

python -c "
import asyncio
import os
from copernicus_mcp.server import get_auth_token

async def test():
    result = await get_auth_token()
    if isinstance(result, dict) and 'access_token' in result:
        print('✅ Authentication successful!')
        print(f'Token length: {len(result[\"access_token\"])} characters')
    else:
        print(f'❌ Authentication failed: {result.get(\"error\", \"Unknown error\")}')

asyncio.run(test())
"

📡 Running the Server

Basic Usage

# Run the MCP server
python -m copernicus_mcp

# Or using the module directly
python -m copernicus_mcp.server

Command Line Options

# Show version
python -m copernicus_mcp --version

# Show help
python -m copernicus_mcp --help

🔧 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)

🏗️ Architecture

Server Structure

copernicus-mcp/
├── copernicus_mcp/          # Main package
│   ├── server.py           # Complete server implementation
│   ├── __init__.py         # Package exports
│   └── server_corrupted_backup.py  # Backup
├── examples/               # Usage examples
│   └── example_download_usage.py
├── requirements.txt        # Python dependencies
├── pyproject.toml         # Project configuration
├── README.md              # This file
├── mcp_config.json        # MCP client configuration
└── INSTALL.md             # Installation guide

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

🛠️ Available Tools

Search & Discovery Tools

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:

# Search for Sentinel-2 images over Paris
search_copernicus_images(
    geometry=[[2.2945, 48.8584], [2.2945, 48.8604], [2.2965, 48.8604], [2.2965, 48.8584]],
    geometry_type="polygon",
    mission="sentinel-2",
    start_date="2024-01-01",
    end_date="2024-01-31",
    max_cloud_cover=20,
    max_results=10
)

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.

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.

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)

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

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:

# Download a quicklook preview
download_image(
    image_id="S2B_MSIL2A_20240115T105629_N0510_R094_T31UCS_20240115T130259",
    mission="sentinel-2",
    download_type="quicklook"
)

# Download full product
download_image(
    image_id="S2B_MSIL2A_20240115T105629_N0510_R094_T31UCS_20240115T130259",
    mission="sentinel-2",
    download_type="full"
)

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:

batch_download_images(
    image_ids=["id1", "id2", "id3"],
    mission="sentinel-2",
    download_type="quicklook",
    max_concurrent=2
)

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:

# Search and download best image
search_and_download(
    geometry=[-122.4194, 37.7749],  # San Francisco
    geometry_type="point",
    mission="sentinel-2",
    start_date="2024-01-01",
    end_date="2024-01-31",
    download_type="quicklook"
)

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.

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

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:

list_downloaded_files(
    download_dir="my_downloads",
    file_type="quicklook",
    limit=10
)

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:

# Dry run - see what would be deleted
cleanup_downloads(
    download_dir="downloads",
    older_than_days=30,
    dry_run=True
)

# Actually delete files older than 30 days
cleanup_downloads(
    download_dir="downloads",
    older_than_days=30,
    dry_run=False
)

# Keep total size under 10GB
cleanup_downloads(
    download_dir="downloads",
    max_size_mb=10240,
    dry_run=False
)

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

# 1. Search for images
search_results = search_copernicus_images(
    geometry=[-122.4194, 37.7749],  # San Francisco
    geometry_type="point",
    mission="sentinel-2",
    start_date="2024-01-01",
    end_date="2024-01-31",
    max_cloud_cover=30,
    max_results=5
)

# 2. Extract image IDs
image_ids = [img["Id"] for img in search_results.get("products", [])]

# 3. Check availability
availability = check_download_availability(image_ids[:2])

# 4. Download quicklooks for available images
for image_id in image_ids[:2]:
    download_image(
        image_id=image_id,
        mission="sentinel-2",
        download_type="quicklook"
    )

# 5. List downloaded files
files = list_downloaded_files(
    download_dir="downloads",
    file_type="quicklook"
)

# 6. Get statistics
stats = get_download_statistics()

🔒 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 Performance

• Progress Reporting: Updates every 10 seconds or 100MB
• Extended Timeouts: Up to 2 hours for large downloads
• Chunk Size: 1MB chunks for optimal throughput
• Concurrent Downloads: Configurable (default: 3 concurrent)

Timeout Configuration

The server uses appropriate timeouts for different operations:

• Small files (quicklooks): 2 minutes
• Medium files (compressed): 1 hour
• Large files (full products): 2 hours
• API requests: 1 minute

MCP Client Compatibility

• All progress sent to stderr with regular flushing
• Clients must monitor stderr for progress updates
• Connection kept alive through periodic output

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

🚨 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
• 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

Testing Your Setup

# Test timeout fixes
python test_download_timeout.py

# Test with example downloads
python example_download_usage.py

Common Issues and Solutions

Authentication Failures

# Check if credentials are set
echo $COPERNICUS_USERNAME
echo $COPERNICUS_PASSWORD

# Test authentication directly
python -c "
import asyncio
from copernicus_mcp.server import get_auth_token
async def test():
    result = await get_auth_token()
    print('Result:', result)
asyncio.run(test())
"

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:

export COPERNICUS_DEBUG_AUTH=true
python -m copernicus_mcp

Log Files

• Check application logs for detailed error messages
• Monitor download progress in real-time
• Review cleanup operations before execution

🚨 Zed Timeout Fixes

Issue Description

Zed IDE (and other MCP clients) expect MCP tools to complete quickly (typically within 30-60 seconds). However, full satellite image downloads might take hours to complete. This mismatch causes Zed to kill download processes prematurely. you can increase MCP Tool timeout in Zed settings.

🙏 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
• Configuration examples in mcp_config.json