Skip to main content
Glama
source-coop-mcp

source-coop-mcp

by yharby

Source Cooperative MCP Server

Tests PyPI version Python 3.11+ License: MIT

Discover and access 800TB+ of geospatial data through AI agents.

An MCP (Model Context Protocol) server for Source Cooperative - a collaborative repository with datasets from Maxar, Harvard, ESA, USGS, and 90+ organizations.


šŸ—ļø Architecture Overview

graph TB
    subgraph "AI Clients"
        A1[Claude Desktop]
        A2[Claude Code]
        A3[Cursor]
        A4[Cline]
        A5[Zed]
        A6[Continue.dev]
    end

    subgraph "MCP Server"
        MCP[Source Cooperative MCP<br/>FastMCP + obstore]
    end

    subgraph "6 Available Tools"
        T1[list_accounts<br/>94+ orgs]
        T2[list_products<br/>hybrid S3+API]
        T3[get_product_details<br/>+ README]
        T4[list_product_files<br/>tree mode]
        T5[get_file_metadata<br/>no download]
        T6[search<br/>hybrid fuzzy]
    end

    subgraph "Data Sources"
        S1[HTTP API<br/>source.coop/api]
        S2[S3 Direct<br/>opendata.source.coop]
    end

    A1 -->|JSON-RPC| MCP
    A2 -->|JSON-RPC| MCP
    A3 -->|JSON-RPC| MCP
    A4 -->|JSON-RPC| MCP
    A5 -->|JSON-RPC| MCP
    A6 -->|JSON-RPC| MCP

    MCP --> T1
    MCP --> T2
    MCP --> T3
    MCP --> T4
    MCP --> T5
    MCP --> T6

    T1 --> S2
    T2 --> S1
    T2 --> S2
    T3 --> S1
    T3 --> S2
    T4 --> S2
    T5 --> S2
    T6 --> S1

    style MCP fill:#4CAF50,stroke:#2E7D32,stroke-width:3px,color:#fff
    style S1 fill:#2196F3,stroke:#1976D2,stroke-width:2px,color:#fff
    style S2 fill:#2196F3,stroke:#1976D2,stroke-width:2px,color:#fff

Key Features:

  • āœ… Token Optimized - 72% reduction for large datasets

  • āœ… Smart Partitions - Auto-detects Hive-style patterns

  • āœ… Fuzzy Search - Handles typos and partial matches

  • āœ… No Auth - All 800TB+ is public


Related MCP server: SkyFi MCP Server

šŸš€ Quick Start

Install

uvx source-coop-mcp

Configure Your AI Client

Claude Desktop / Claude Code / Cursor / Cline

Add to config file:

  • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

  • Claude Code: VS Code settings.json

  • Cursor: Cursor settings

  • Cline: Cline MCP settings

{
  "mcpServers": {
    "source-coop": {
      "command": "uvx",
      "args": ["source-coop-mcp"]
    }
  }
}

Zed

Add to Zed settings:

{
  "context_servers": {
    "source-coop": {
      "command": "uvx",
      "args": ["source-coop-mcp"]
    }
  }
}

Continue.dev

Add to Continue config (~/.continue/config.json):

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uvx",
          "args": ["source-coop-mcp"]
        }
      }
    ]
  }
}

Restart your AI client and start exploring!


šŸ› ļø Available Tools

Tool

Purpose

Performance

list_accounts()

Find all 94+ organizations

~850ms

list_products()

Hybrid: S3 mode (default) for ALL datasets + file counts

~240ms

list_products(include_unpublished=False)

API mode for published datasets with rich metadata

~500ms

get_product_details()

Get metadata + README automatically

~650ms

list_product_files()

List files with S3/HTTP paths

~240ms

list_product_files(show_tree=True)

Tree view (72% token savings)

~980ms

get_file_metadata()

Get file info without downloading

~230ms

search(query)

Hybrid: Search accounts + products (published + unpublished), top 5 results

~5-10s


šŸ’” What You Can Do

Discover Data

"List all organizations in Source Cooperative"
→ Returns 94+ organizations: maxar, planet, harvard, etc.

"Find all datasets for harvard-lil"
→ Discovers published + unpublished products

"Search for climate datasets"
→ Smart fuzzy search handles typos and partial matches

Access Files

"List files in harvard-lil/gov-data"
→ Returns S3 paths and HTTP URLs ready for analysis

"Show me the file tree with partition detection"
→ Smart visualization: year={2020,2021,...+5 more}/ [partitioned]

"Get file metadata without downloading"
→ Size, last modified, ETag
"Search for climte" (typo)
→ Finds "climate" datasets (fuzzy matching)

"Search for geo" (partial)
→ Finds "geospatial", "geocoding", etc.

⚔ Features

Feature

Description

Complete Discovery

Finds unpublished products the official API doesn't show

No Authentication

All 800TB+ data is public

Fast Performance

Rust-backed S3 client (9x faster than boto3)

Token Optimized

Tree mode: 72% token reduction for large datasets

Smart Partitions

Auto-detects patterns: year={2020,2021,...}

Fuzzy Search

Handles typos and partial matches

README Integration

Documentation automatically included

800TB+ Data

94+ organizations, geospatial datasets


šŸ“‹ Example Workflow

1. "List all organizations"
   → Get 94+ account names

2. "Show me all datasets from maxar"
   → Discover published + unpublished products

3. "Search for climate data"
   → Smart fuzzy search finds relevant datasets

4. "Get details for harvard-lil/gov-data"
   → Full metadata + README content

5. "List files in this dataset with tree view"
   → Token-optimized tree with partition detection

šŸŽÆ Why This Server?

Problem

Source Cooperative has 800TB+ of valuable data, but:

  • Official API only shows published products

  • No auto-discovery of organizations

  • Requires knowing what you're looking for

Solution

This MCP server provides:

  • āœ… Complete auto-discovery (published + unpublished)

  • āœ… Smart search with fuzzy matching

  • āœ… Direct S3 access for all files

  • āœ… Token-optimized outputs (72% reduction)

  • āœ… Smart partition detection (10-88% additional savings)

  • āœ… README documentation included automatically

  • āœ… No authentication required


šŸ“Š Performance

All operations complete in under 1 second:

list_accounts():                          ~850ms  (94+ organizations)
list_products():                          ~240ms  (S3 mode - ALL datasets + file counts)
list_products(include_unpublished=False): ~500ms  (API mode - published with metadata)
list_product_files():                     ~240ms  (simple list)
list_product_files(tree=True):            ~980ms  (72% token savings)
get_file_metadata():                      ~230ms  (HEAD only)
search(query):                            ~5-10s  (hybrid search - 1 recursive S3 scan, top 5 enriched)

Token Optimization Impact

Dataset Size

Without Tree

With Tree

Saved

10 files

1,500 tokens

415 tokens

72.3%

100 files

15,000 tokens

4,150 tokens

72.3%

1,000 files

150,000 tokens

41,500 tokens

72.3%

With partition detection (1,000 partitions): 88% total savings!


šŸ”§ Requirements

  • Python: 3.11 or higher

  • Package Manager: uv (installed automatically by uvx)

  • Operating Systems: macOS, Linux, Windows


šŸ¤ Development

See DEVELOPMENT.md for:

  • Architecture details

  • Testing instructions

  • Contributing guidelines

  • Performance benchmarks

  • Token optimization details


šŸ“ Support


šŸ“„ License

MIT License - see LICENSE for details.

Available Tools

6 tools
get_file_metadataA

Get metadata for a specific file without downloading it. Uses obstore's head operation for efficient metadata retrieval.

Args: path: S3 URI (s3://...) or relative path (account_id/product_id/file)

Returns: File metadata: size, content-type, last-modified, etag, URLs

Example: >>> await get_file_metadata("harvard-lil/gov-data/README.md") { "key": "harvard-lil/gov-data/README.md", "content_type": "binary/octet-stream", "content_length": 5344, "last_modified": "2025-02-06T16:29:24+00:00", ... }

Inputs: path (required). Returns: object

get_product_detailsA

Get comprehensive metadata for a specific product. Always includes README content if found in the product root directory.

Args: account_id: Account ID (e.g., "harvard-lil") product_id: Product ID (e.g., "gov-data")

Returns: Full product metadata including account info, storage config, roles, tags Always includes 'readme' field with content and metadata (if README exists)

Example: >>> await get_product_details("harvard-lil", "gov-data") { "title": "Archive of data.gov", "description": "...", "account": {"name": "Harvard Library Innovation Lab", ...}, "readme": { "found": true, "content": "# Archive of data.gov...", "size": 5344, "path": "harvard-lil/gov-data/README.md" }, ... }

Inputs: account_id (required), product_id (required). Returns: object

list_accountsA

Discover all organizations/accounts in Source Cooperative.

Returns: List of account IDs (e.g., ['clarkcga', 'harvard-lil', 'youssef-harby'])

Example: >>> await list_accounts() ['addresscloud', 'clarkcga', 'harvard-lil', ...]

Inputs: no named parameters. Returns: result

list_product_filesA

List all files in a product with full S3 paths ready for analysis. Optionally show a hierarchical tree visualization (optimized for LLM tokens).

Args: account_id: Account ID product_id: Product ID prefix: Optional prefix to filter files (subdirectory path) max_files: Maximum files to return (default 1000) show_tree: If True, return tree visualization only (more token-efficient, default True)

Returns: Dict with either files list OR tree visualization (not both to save tokens)

Example (List mode - detailed metadata): >>> result = await list_product_files("harvard-lil", "gov-data", "metadata/") >>> print(result["files"][0]) { "key": "harvard-lil/gov-data/metadata/metadata.jsonl.zip", "s3_uri": "s3://us-west-2.opendata.source.coop/harvard-lil/gov-data/metadata/metadata.jsonl.zip", "http_url": "https://data.source.coop/harvard-lil/gov-data/metadata/metadata.jsonl.zip", "size": 1012127330, "last_modified": "2025-02-06T16:20:22+00:00" }

Example (Tree mode - token optimized): >>> result = await list_product_files("harvard-lil", "gov-data", show_tree=True) >>> print(result["tree"]) s3://us-west-2.opendata.source.coop/harvard-lil/gov-data/ ā”œā”€ā”€ README.md (5.2 KB) → s3://...README.md ā”œā”€ā”€ metadata/ │ └── metadata.jsonl.zip (965.4 MB) → s3://...metadata.jsonl.zip └── data/ └── datasets.parquet (128.5 MB) → s3://...datasets.parquet

Example (Partitioned data - smart summarization): >>> result = await list_product_files("account", "product", show_tree=True) >>> print(result["tree"]) s3://us-west-2.opendata.source.coop/account/product/ ā”œā”€ā”€ year={1995,1996,...,2007 (13 total)}/ [partitioned] │ └── format={ixi,pxp}/ [partitioned] │ └── matrix={F_impacts,F_satellite,Y,Z}/ [partitioned] │ └── data.parquet (5.1 MB)

Note: Shows first,second,...,last (total) for >10 values; lists all for ≤10
Tree mode saves ~70% tokens + smart partition detection saves 96%+ more

Inputs: account_id (required), product_id (required), prefix, max_files, +1 more. Returns: object

list_productsA

List products (datasets) in Source Cooperative with hybrid S3 + API approach.

DEFAULT: Uses S3 direct scan (fast, includes ALL products with file counts). Set include_unpublished=False for published-only with rich metadata from API.

Args: account_id: Filter by specific account. REQUIRED for S3 mode (default). If None with include_unpublished=False, lists published from all accounts. featured_only: Only return featured/curated products (API mode only). include_unpublished: If True (default), scan S3 for ALL products including unpublished. If False, use API for published products with rich metadata. include_file_count: Count files in each product (default True, only in S3 mode).

Returns: S3 mode (default): Basic info (product_id, s3_prefix, file_count) - fast! API mode: Rich metadata (product_id, title, description, dates) - slower

Performance: - S3 mode (default): ~240ms, includes unpublished products + file counts - API mode (include_unpublished=False): ~500ms, rich metadata, published only

Examples: >>> # ALL products with file counts (DEFAULT - fast!) >>> await list_products(account_id="youssef-harby") [ {"product_id": "exiobase-3", "source": "s3", "file_count": 1000, ...}, {"product_id": "egms-copernicus", "source": "s3", "file_count": 53, ...}, ... ]

>>> # Published products with rich metadata (API mode)
>>> await list_products(account_id="youssef-harby", include_unpublished=False)
[{"product_id": "egms-copernicus", "title": "...", "description": "...", ...}]

>>> # Fast mode without file counts
>>> await list_products(account_id="youssef-harby", include_file_count=False)
[{"product_id": "exiobase-3", "source": "s3", ...}]

>>> # Featured products only (requires API mode)
>>> await list_products(featured_only=True, include_unpublished=False)
[{"product_id": "gov-data", "featured": 1, ...}]

Inputs: account_id, featured_only, include_unpublished, include_file_count. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose: metadata retrieval for files vs. products, listing accounts, products, or files, and a separate search function. No overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (get_file_metadata, list_accounts, search, etc.) using lowercase with underscores. Highly predictable and uniform.

    Tool Count5/5

    Six tools is ideal for a data catalog server, covering discovery, browsing, and search without being overwhelming or too sparse.

    Completeness5/5

    The tool surface covers all essential operations for exploring a data cooperative: listing accounts, products, files, retrieving detailed metadata, and cross-account search. No obvious gaps.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to search and access geospatial datasets through STAC (SpatioTemporal Asset Catalog) APIs. Supports querying satellite imagery, weather data, and other geospatial assets with spatial, temporal, and attribute filters.
      11
      20
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Turns the AWS Registry of Open Data and public STAC catalogs into agent-callable tools for dataset search, STAC queries, and NDVI/NDBI/land-cover analysis on Sentinel-2 imagery.
      -