DEPOSIUM GeoAI
by theseedship
README.md
# DEPOSIUM GeoAI
**Satellite observations, weather and spatial data — accessible through AI tools.**
GeoAI turns geospatial data into structured, traceable results that an AI client
can retrieve, analyse and explain. Ask for a weather forecast at a point, inspect
vegetation over an area, or look for relationships in environmental time series.
The server retrieves data and runs the calculations. Tools expose explicit
inputs and structured results, with source and limit metadata where available.
GeoAI is a **self-hosted Python MCP server**. The
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) lets compatible
AI applications call its tools. Install it with `uv` or build its Docker image,
then configure your MCP client to launch it locally or connect to your running
instance over HTTP. It works with compatible MCP clients independently of the
DEPOSIUM application. See [installation options](#install-geoai),
[Docker deployment](#optional-docker-deployment) and
[hosting and data flow](#hosting-and-data-flow).
## Funded by FIERCE
<p>
<a href="https://project-fierce.eu/">
<img src="assets/fierce-logo.png" alt="FIERCE — Making Space for Green Solutions" width="140">
</a>
<a href="https://project-fierce.eu/about/">
<img src="assets/eu-funded.jpg" alt="Funded by the European Union" width="287">
</a>
</p>
**GeoAI is funded by the [FIERCE project](https://project-fierce.eu/)** through
its Financial Support Programme. This support brings together research,
geospatial engineering and market exploration to help DEPOSIUM work with Earth
Observation and environmental data.
FIERCE receives European Union support through Horizon Europe, Grant Agreement
**101177496**. See the [official project description](https://project-fierce.eu/about/).
The authors are responsible for this repository's content; it does not represent
an endorsement by the European Union or HADEA.
## Team and contributions
The project combines complementary research, engineering and market expertise.
| Contributor | Role in the project |
| --- | --- |
| **[Nicolas Geysse](https://github.com/nicolas-geysse)** — [DEPOSIUM / TSS](https://deposium.ai/) | Project lead and coordination; architecture and implementation of the MCP layer, product direction, integration into DEPOSIUM and qualification of user workflows. |
| **[Jonathan Labéjof, PhD](https://github.com/b3j0f)** — [BEJOF](https://www.bejof.org/) | Geospatial data pipelines, reproducible processing, forecast integration and evaluation infrastructure. |
| **[Dickson Owuor, PhD](https://github.com/owuordickson)** — [so4gp](https://pypi.org/project/so4gp/) | Scientific methods for gradual-pattern mining; library development, experimental comparisons and research validation. |
| **[Amandine Raynaud](https://www.linkedin.com/in/amandine-raynaud/)** — [CLELYA](https://clelya.fr/vision/) | Market study and innovation strategy: identify relevant sectors, practical problems and conditions for adoption. |
The scientific foundations include Dickson Owuor and Anne Laurent's work on
gradual-pattern mining and related collaborations. Method and software credits
are recorded in [CITATION.cff](CITATION.cff).
## Start here
| I want to… | Read |
| --- | --- |
| Understand the project and its research question | [Why GeoAI?](#why-geoai) |
| Meet the project team | [Team and contributions](#team-and-contributions) |
| See what I can do with it | [Capabilities](#capabilities) |
| Choose a tool or try a first request | [MCP tools: 16 tools, inputs and examples](reference/mcp-tools.md) |
| Choose how to install or host GeoAI | [Installation options](#install-geoai) |
| Connect my MCP client | [Run locally](#run-locally) |
| Understand where the server runs and which data it receives | [Hosting and data flow](#hosting-and-data-flow) |
| Run the server in a container | [Optional Docker deployment](#optional-docker-deployment) |
| Configure providers and storage | [Configuration](#configuration) |
| Understand the scientific scope | [Research and evidence](#research-and-evidence) |
| Understand computation, providers and S3 storage | [Architecture and data flow](docs/architecture.md) |
| Compare delivered scope and next objectives | [Roadmap](docs/roadmap.md) |
| Review FIERCE technical evidence and reported KPI status | [Public evidence index](docs/evidence/README.md), [technical KPI annex](docs/evidence/fierce-kpi-evidence.en.md) and [Word edition](docs/evidence/fierce-kpi-evidence.en.docx) |
| Develop, test or contribute | [Development](#development) |
| Cite the work or check reuse conditions | [Copy a citation or BibTeX](#citation), [sources and methods](#data-sources-and-attribution), [licence](#licence) and [full notices](NOTICE) |
## Why GeoAI?
[DEPOSIUM®](https://deposium.ai/), developed by
[The Seed Ship (TSS)](https://the-seed-ship.com/), helps people work with documents
and knowledge. GeoAI extends that direction to data with a location and a time:
satellite acquisitions, weather series, geographic features and their sources.
The guiding research question is:
> **Can we extract more knowledge with less computation?**
The work connects data preparation, temporal analysis, gradual-pattern mining
and AI-assisted exploration. It asks how to make complex environmental data
usable while keeping computation explicit and reproducible. Computational and
environmental efficiency are objectives to evaluate on defined workloads.
Within DEPOSIUM, these tools provide a foundation for connecting environmental
observations to documents and conversational workflows. This repository delivers
the independent GeoAI server; the consuming application supplies its interface,
document retrieval, scheduling and notification delivery.
## Capabilities
| Work with… | What GeoAI provides | Tools |
| --- | --- | --- |
| **Satellite observations** | Find scenes, obtain band URLs, compute NDVI profiles and vegetation indicators, compare two observation windows. | [Satellite and vegetation tools](reference/mcp-tools.md#satellite-imagery-and-vegetation) |
| **Weather and climate** | Daily forecasts for a point or zone, historical daily weather, monthly climate distributions and alignment with NDVI acquisitions. | [Weather and climate tools](reference/mcp-tools.md#weather-and-climate) |
| **Geographic layers** | Select GeoParquet features by intersection, containment or distance. | [Spatial queries](reference/mcp-tools.md#spatial-queries) |
| **Environmental time series** | Discover attributes that vary together, test their recurrence across zone folds and calculate experimental explanatory indices. | [Pattern tools](reference/mcp-tools.md#patterns-and-experimental-alerts) |
| **Solar profiles** | Validate or collect a bounded portfolio of hourly radiation data, with explicit provider-access configuration. | [Solar acquisition pilot](reference/mcp-tools.md#solar-acquisition-pilot) |
The server advertises **16 tools** with structured input/output contracts. An MCP
client can read `geoai://capabilities/tools` for the authoritative inventory and
`geoai://guide/agent` for workflow guidance. See the
[plain-language tool reference and first calls](reference/mcp-tools.md#first-calls).
## From data sources to usable results
Each tool uses the relevant path below. Solid arrows show data and results;
dashed arrows show supported storage operations.
```mermaid
flowchart LR
SatelliteSource["Satellite sources<br/>Sentinel-2 / STAC"]
WeatherSource["Weather sources<br/>Open-Meteo<br/>ERA5 / IFS / AIFS"]
Storage[("Your optional S3 store<br/>GeoParquet / artifacts")]
subgraph Server["Your GeoAI MCP server — local process, Docker or remote service"]
Satellite["Satellite / vegetation<br/>Rasterio / NDVI"]
Climate["Weather / climate<br/>Forecasts / normals"]
Analysis["Spatial queries / patterns<br/>DuckDB / optional so4gp"]
end
Client["Your MCP client<br/>Structured results<br/>Sources and limits"]
SatelliteSource --> Satellite --> Client
WeatherSource --> Climate --> Client
Storage --> Analysis --> Client
Storage -. "read climate series" .-> Climate
Satellite -. "ingestion writes" .-> Storage
Climate -. "explicit persistence" .-> Storage
Analysis -. "derived outputs" .-> Storage
```
Storage is optional for storage-free tools. Supported writes and archive commands
persist explicitly; every MCP response is not automatically written to S3.
Permitted local Parquet inputs are also supported when explicitly enabled.
Archive CLIs provide separate local/S3 workflows.
The consuming application supplies UI, document retrieval, scheduling and
notification delivery. See [the architecture](docs/architecture.md) for source
links and [the objective/evidence index](docs/evidence/README.md) for dated proof.
## Hosting and data flow
GeoAI must be running for a client to call its tools. Choose how to run it:
- **Local process (stdio):** install the Python dependencies with `uv` and
configure the MCP client to launch GeoAI on your computer. The client exchanges
requests and results directly with that process.
- **HTTP service:** deploy GeoAI with Python or Docker, on your computer or on
infrastructure you control. Configure the client with the instance's `/mcp`
URL and bearer credentials. The operator of that instance controls its hosting,
access and storage. Legacy SSE is also supported.
MCP defines how a client communicates with a server; it does not provide hosting
or require a central GeoAI collector. Packages distributed through npm may also
launch local MCP server programs. This project's installation uses Python/`uv`
or Docker.
The selected GeoAI instance receives the arguments of tool calls, such as
coordinates, dates, variables or dataset references. Depending on the tool and
configuration, it contacts satellite/weather providers, reads permitted local or
S3 data, and performs supported storage writes. A local deployment can therefore
still make outbound provider requests. Local file paths always refer to the
server's filesystem, including when the server is hosted remotely.
The consuming application decides which conversation or document data it sends
in tool calls and which returned results it passes to a language model. It must
also enforce user and tenant permissions; a shared HTTP bearer credential only
controls access to the GeoAI service. See [the architecture](docs/architecture.md)
for these boundaries and the optional S3 data flow.
## Research and evidence
The engineering layer makes data and calculations accessible through MCP. The
research layer investigates which interpretable relationships can be extracted
and whether they help on a defined task. Experimental comparisons, including
negative results, are kept reproducible through code, fixtures and source hashes.
The optional pattern tools use native **so4gp GRAANK and TGrad**.
A pattern describes an association to assess; it does not establish a cause or a
calibrated prediction. Explanatory indices are not event probabilities. NDVI
measures vegetation greenness, with separate validation needed for claims about
carbon or biodiversity. Weather results retain their actual provider, collection
time and missing-data limits; model issuance remains unknown when unavailable.
These foundations can support further work in agriculture, environmental
monitoring and renewable energy. New indicators and missing-data estimation need
a suitable dataset, an explicit method and their own validation protocol.
## Install GeoAI
You can install and operate your own instance; a DEPOSIUM account is not required.
Choose the setup that fits your MCP client:
| Setup | What runs where | What you need |
| --- | --- | --- |
| [Local Python / stdio](#run-locally) | Your MCP client launches GeoAI on your computer. | Git, Python 3.14 and `uv`; a client that supports stdio. |
| [Local Docker / HTTP](#optional-docker-deployment) | GeoAI runs in a local container; your client connects to `http://127.0.0.1:5001/mcp`. | Git, Docker Engine with Compose; a client that supports HTTP. |
| [Remote HTTP service](#remote-http-deployment) | An operator runs GeoAI on their infrastructure; clients connect to its HTTPS URL. | The operator installs Python or Docker; client users need the URL and credentials. |
For either self-hosted installation, first clone this repository:
```sh
git clone https://github.com/theseedship/mcp_geoai_deposium.git
cd mcp_geoai_deposium
```
Continue with one of the setup sections below. The repository supplies the
server and configuration examples; your chosen MCP application supplies the chat
interface. Queries to external data providers need internet access and remain
subject to those providers' access conditions.
## Run locally
Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then run
the following from the cloned directory. This installs Python 3.14 and the locked
CPU pattern runtime:
```sh
uv python install 3.14
uv sync --locked --extra patterns
```
Configure your MCP client to launch the server process. The following common
`mcpServers` configuration uses stdio; adapt its location/format to your client
and replace the directory with the absolute path to your checkout:
```json
{
"mcpServers": {
"geoai": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/geoai", "run", "--no-sync", "geoai-server"],
"env": {"MCP_TRANSPORT": "stdio"}
}
}
}
```
The optional pattern profile includes so4gp and CPU PyTorch. It supports Linux,
Windows and macOS 14+ on ARM64; the Torch-backed extras do not support Intel
macOS. The dependency and platform policy is recorded in [pyproject.toml](pyproject.toml).
For HTTP, choose a bearer secret of at least 32 characters and pass it to the
server and client:
```sh
export GEOAI_MESH_AUTH_TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
MCP_TRANSPORT=http HOST=127.0.0.1 PORT=5001 uv run --no-sync geoai-server
```
The MCP endpoint is `http://127.0.0.1:5001/mcp`; `/health` returns `OK`.
`GEOAI_MESH_AUTH_TOKEN` is a local server configuration name: any MCP HTTP client
can use it as an `Authorization: Bearer …` header. HTTP/SSE data-plane startup
requires this token. Stdio uses the parent process boundary instead.
## Optional Docker deployment
The supplied Compose file starts only the GeoAI server. It binds to loopback,
uses the locked CPU pattern dependencies and creates one data volume. From the
cloned directory (the example uses Python 3 to generate a random bearer secret):
```sh
export GEOAI_MESH_AUTH_TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
docker compose up --build -d
curl http://127.0.0.1:5001/health
```
Compose builds the image from this checkout. After `/health` returns `OK`,
configure an HTTP-capable MCP client with `http://127.0.0.1:5001/mcp` and an
`Authorization: Bearer ...` header containing the same secret. The `/mcp` endpoint
speaks MCP; use your MCP application to call its tools.
No GPU, database or object-store service is launched. To use S3-backed tools,
provide your own endpoint and credentials. To change the published port, set
`GEOAI_HOST_PORT` in your shell, for example `5051`.
## Remote HTTP deployment
The operator installs the same Python service or builds the Docker image on
their own server or cloud platform, configures the provider/storage access they
need, and exposes `/mcp` through an authenticated HTTPS endpoint. The supplied
Compose file binds to loopback; remote access requires the operator to configure
HTTPS ingress or a reverse proxy for their deployment.
Client users then configure that instance's URL and bearer credentials. They do
not need a local Python or Docker installation. The public repository supplies
the server code; it does not supply a shared hosted endpoint or service account.
The operator must manage user access and decide which datasets the instance can
read. See [hosting and data flow](#hosting-and-data-flow) and
[configuration](#configuration).
## Try a first request
Once connected, list the available tools and ask your MCP client to call
`forecast_query` with:
```json
{"latitude": 43.6, "longitude": 3.88, "forecast_days": 3, "provider": "auto", "write_output": false}
```
This requests a three-day forecast at the supplied Montpellier coordinates
without saving it to S3. The returned coordinates, provider/model, units,
collection timestamp and missing-data metadata should remain visible in the
client's answer. See [first tool calls](reference/mcp-tools.md#first-calls) for
satellite and NDVI examples. Stored-data tools additionally require your own
configured datasets/storage; installing the server does not populate a climate
archive or qualify patterns automatically.
## Configuration
See `.env.example` for common server settings and `src/config.py` for the
complete validated settings. A local `.env` file is optional and ignored by Git.
| Setting | Purpose |
| --- | --- |
| `MCP_TRANSPORT` | `http` (default), `stdio` or `sse` |
| `HOST`, `PORT` | Network bind address and port; ignored for stdio |
| `GEOAI_MESH_AUTH_TOKEN` | Optional HTTP bearer; required when enabling data-plane access |
| `STAC_URL` | Satellite catalogue; defaults to public Earth Search |
| `S3_ENDPOINT`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, `S3_BUCKET` | Your S3-compatible storage, when needed |
| `ALLOW_LOCAL_PARQUET_SOURCE`, `LOCAL_PARQUET_SOURCE_ROOT` | Explicit opt-in to a confined local Parquet directory |
| `FORECAST_API_BASE_URL`, `FORECAST_API_KEY` | Forecast endpoint and optional matching API key |
Storage is optional for starting the server. Local Parquet access is disabled
by default; enabling it requires an absolute allowed directory other than `/`.
S3 paths retain explicit tenant/space prefixes. Do not treat a supplied path or
an evidence digest as caller authorization.
Solar collection has separate opt-in settings in `src/solar_pilot.py`; an
example is `examples/solar.env.example`. Use the provider access and endpoint
appropriate to your use. External APIs, imagery and datasets retain their own
access conditions, attribution and licences.
## Development
```sh
uv sync --locked --extra dev --extra patterns
uv run --no-sync ruff check .
uv run --no-sync ruff format --check .
OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 MKL_NUM_THREADS=1 PYTHONHASHSEED=0 \
uv run --no-sync pytest tests/
```
`tests/live_acceptance.py` is a separate opt-in harness requiring a running
server and configured test storage. The normal test suite runs offline with
synthetic or frozen fixtures. Packaged runtime examples retain their scientific
scope and provenance; they are not a certification of operational forecasts.
Public documentation is maintained in this README, the
[MCP tools reference](reference/mcp-tools.md), [architecture](docs/architecture.md),
[roadmap](docs/roadmap.md) and [curated evidence collection](docs/evidence/README.md).
Only these selected public documentation paths are included. Other local project
documents, `docs-private/`, `research-data/` and `outputs/` remain excluded;
adding local documents does not expose them as MCP resources.
## Data sources and attribution
GeoAI builds on the work of data producers, distributors and researchers.
Please credit the sources actually used in your outputs, including the underlying
weather model when a provider fallback occurs.
| Data or method | Source and credit |
| --- | --- |
| Weather and climate API access | [Open-Meteo](https://open-meteo.com/); [API data licence and attribution](https://open-meteo.com/en/licence). |
| ERA5 reanalysis | Copernicus Climate Change Service / ECMWF; [dataset and DOI](https://doi.org/10.24381/cds.adbb2d47), accessed through Open-Meteo. |
| IFS/AIFS forecasts | [ECMWF open data](https://www.ecmwf.int/en/forecasts/datasets/open-data), accessed through Open-Meteo; [ECMWF terms](https://apps.ecmwf.int/datasets/licences/general/). |
| Sentinel-2 imagery and derived NDVI | ESA / Copernicus; [Earth Search by Element 84](https://earth-search.aws.element84.com/v1/collections/sentinel-2-l2a). The catalogue also credits Sinergise processing and AWS hosting. |
| Montpellier and Fos administrative boundaries | IGN, [ADMIN EXPRESS COG](https://geoservices.ign.fr/adminexpress); source and retrieval metadata in [CITATION.cff](CITATION.cff). |
| Lez catchment boundaries | IGN / OFB, distributed by Sandre: [BD TOPAGE® Métropole 2026](https://www.data.gouv.fr/datasets/bd-topage-r-metropole-2026). |
| Retained historical GFS example | NOAA / NCEP, obtained directly from the [NOAA public archive](https://registry.opendata.aws/noaa-gfs-bdp-pds/), separately from Open-Meteo; [usage conditions](https://www.weather.gov/disclaimer). |
Gradual-pattern mining uses **[so4gp](https://pypi.org/project/so4gp/1.1.2/)** by
**Dickson Owuor and Anne Laurent**. Cite the methods used: GRAANK by
[Laurent, Lesot and Rifqi (2009)](https://doi.org/10.1007/978-3-642-04957-6_33),
and fuzzy-temporal gradual patterns by
[Owuor, Laurent and Orero (2019)](https://doi.org/10.1109/FUZZ-IEEE.2019.8858883).
Core engineering libraries include [FastMCP](https://pypi.org/project/fastmcp/),
[Rasterio](https://rasterio.readthedocs.io/) and [DuckDB](https://duckdb.org/).
GeoAI aggregates weather series, derives NDVI and performs spatial/temporal
transformations. Third-party data retain their own licences; the software's MIT
licence does not relicense those data. [NOTICE](NOTICE) records attribution,
modification notices and source-specific conditions;
[CITATION.cff](CITATION.cff) contains bibliographic references. Preserve the
applicable notices when displaying or redistributing results, and use the years
and sources of the data you actually processed. API-access and commercial-use
conditions are separate from the data licence.
## Licence
The existing MIT licence is preserved in [LICENSE](LICENSE). Third-party libraries
and data keep their own licences and attribution; see [NOTICE](NOTICE) and [CITATION.cff](CITATION.cff) for
scientific references. Optional `ai` dependencies are outside the default CPU
image and have separate upstream requirements.
## Citation
If you use GeoAI in research, a report or another project, you can copy this
software citation:
```text
Nicolas Geysse, Jonathan Labéjof, Dickson Owuor & Amandine Raynaud (2026).
Deposium GeoAI (version 0.1.0) [Computer software].
https://deposium.ai/
Funded by FIERCE through its Financial Support Programme.
FIERCE receives European Union funding under Horizon Europe,
Grant Agreement 101177496.
```
**BibTeX**
```bibtex
@software{deposium_geoai_2026,
author = {Geysse, Nicolas and Labéjof, Jonathan and Owuor, Dickson and Raynaud, Amandine},
title = {Deposium GeoAI},
year = {2026},
version = {0.1.0},
url = {https://deposium.ai/},
note = {Funded by FIERCE through its Financial Support Programme.
FIERCE receives European Union funding under Horizon Europe,
Grant Agreement 101177496.}
}
```
For reproducibility, also record the commit SHA or release tag you used.
Machine-readable citation metadata and references for the methods and data
are available in [CITATION.cff](CITATION.cff).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues