ICOS carbon and greenhouse-gas observations

eu.icos-cpPublished by icos-cp.euOfficial publisherv0.3.0Updated Nov 7, 2026

ICOS atmosphere, ocean and ecosystem greenhouse-gas observations, with citation and DOI per answer

VerifiedStreamable HTTPWeb executableWeb Search & ScrapingKnowledge & MemoryData & Analytics

Overview

AI-generated overview

Queries ICOS greenhouse-gas and ecosystem observation data — searching variables and stations, estimating and fetching selections, computing statistics, and…

What you can do
  • List datasets and search variables by name, quantity, unit or ECV, then describe one variable in full, including units, coverage and quality-flag reading
  • Find stations carrying a variable by point, box, name or country
  • Estimate the size of a selection before fetching it
  • Fetch observations for one variable filtered by box, time, station, cruise, height and quality control, with a download link for the full selection
  • Compute count, mean, min, max, sum and standard deviation over a whole selection, overall or per station, year, month or day
  • Retrieve the citation text, licence and DOI, and the full list of source data objects for a selection
When to use it
When you need authoritative atmospheric, ocean or ecosystem greenhouse-gas observations and want the assistant to find the right variable and station, size the request, and return statistics or a download link rather than raw rows. Useful for questions about CO2, CH4, N2O, fluxes or station comparisons that must be cited properly.
Requirements
A remote streamable HTTP endpoint; no package or local runtime needed. No authentication or API keys are declared for the public endpoint. Network access to the ICOS service is required.
Before you install
Read-only data access, but every answer carries a citation, licence and DOI that must be passed on to the user. Station ids are case-sensitive and released stores lag behind today, so recent periods need the near-real-time stores. Ocean stores (ICOS ocean versus global SOCAT) are easily confused and must be cited as the one actually used.

Installation

In SourceWeft

  1. Open ICOS carbon and greenhouse-gas observations in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/eu.icos-cp%2Ficos/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "icos-carbon-and-greenhouse-gas-observati": {
      "type": "http",
      "url": "https://mcp.icos-cp.eu/mcp"
    }
  }
}

README

icos-mcp

ICOS carbon and greenhouse-gas observations for AI assistants, over the Model Context Protocol. A thin server over the ICOS zarr proxy (https://zarr.icos-cp.eu): every number comes from the proxy, and every data answer carries the citation, licence and DOI. The plan, and why it is built this way, is docs/plan.md.

Phases 1 and 2: seven read-only tools, five resources, three prompts, and a per-store access policy.

tooldoes
list_datasetsthe stores, with domain, coverage, licence, DOI
search_variablesvariable ids by name, quantity or unit ("methane" finds ch4)
describe_variableone variable in full, with how its QC flag is read
find_stationsthe stations carrying a variable: near a point, in a box, by name or country
estimatehow big a selection is, before fetching it
get_dataat most 2,000 rows, the total, a CSV download URL for the whole selection, the citation
get_citationcitation, licence and DOI from the data passport

Run it

uv run icos-mcp                                   # stdio, for a local clientuv run icos-mcp --transport streamable-http --port 8090   # http://127.0.0.1:8090/mcp

ICOS_PROXY points it at another proxy (the RC, a test instance).

Over HTTP the server also answers GET / with an HTML page in the style of zarr.icos-cp.eu -- built from what it offers an anonymous caller: the endpoint and how to connect, the public datasets, the tools and prompts, the citation rule (landing.py; ICOS_MCP_PUBLIC_URL sets the endpoint it names, default https://mcp.icos-cp.eu) -- and GET /health.

Which stores it offers

DEFAULT-DENY: a store is offered only when a rule names it, whatever the proxy behind the server would serve. Without a config file the rules are exactly the public stores of zarr.icos-cp.eu (config/public.json writes them out). ICOS_MCP_CONFIG=/path/to/config.json sets the proxy, the Host header to send it, the base of download links, and an ordered list of store rules, each public or token:

uv run icos-mcp --show-policy          # what this config offers, to whomuv run icos-mcp --hash-token TOKEN     # the line a tokens_file takes

config/ct122.example.json is the shape for running beside zpd on CT122, where zpd answers for EVERY store on the machine (the shuttle, GlobalView, AGAGE): the public stores by name, those three behind tokens, anything else hidden. A token store is offered to an HTTP caller sending Authorization: Bearer <token> whose SHA-256 is in its tokens_file (plain tokens are never stored); a local stdio caller is the operator and uses ICOS_MCP_TOKEN, which never speaks for an HTTP caller. A hidden store answers exactly as one that does not exist, and the static icos://catalogue resource -- which the protocol does not tell who is asking -- lists the public stores only.

Signing in

An oauth section in the config makes signing in required over HTTP. Anyone can sign in. The aim is to know who uses the server, not to keep anyone out:

"oauth": {"issuer": "https://sso.fs4vm.icos-cp.eu/realms/icos-test",          "audience": "https://mcp.icos-cp.eu"}

The server is only a resource server. ICOS's Keycloak handles the sign-in, through cpauth, Google or ORCID. MCP clients find Keycloak in /.well-known/oauth-protected-resource, register themselves with it and send the user to sign in. A token must be signed by the realm and carry this server's audience, which needs an audience mapper in Keycloak. The store tokens above still work. The landing page and /health stay open, and the stdio operator is never asked to sign in (auth.py).

Signing in also allows a group store rule. The store is offered to members of a Keycloak group, or of a subgroup of one, and to no one else. The groups come from the verified token's groups claim:

{"match": "agage*", "access": "group", "groups": ["agage"], "public_url": "https://agage-zarr.icos-cp.eu"}

Group names are paths below /apps/mcp in the realm: agage is /apps/mcp/agage. That is the only part of a user's groups Keycloak sends this server.

Access is granted and withdrawn in Keycloak, not in the config. A group rule may also list store tokens for scripts. A group rule without an oauth section is refused at load, because nobody could reach it.

In Claude Code:

claude mcp add icos -- uv --directory /path/to/zarrm9/mcp run icos-mcp

Resources: icos://stores/{store}/agent-guide, icos://stores/{store}/croissant, icos://catalogue, icos://llms.txt, icos://data-passport. Prompts: station_record, compare_stations, ocean_region.

Test it

uv run pytest                                 # over RECORDED proxy answers (tests/cassette)ICOS_CASSETTE_MODE=record uv run pytest       # re-record from the live proxyICOS_LIVE=1 uv run pytest                     # live, nothing recordeduv run ruff check src testsconformance/run.sh                            # the MCP conformance suite (needs Node)

conformance/run.sh starts a local server and runs the MCP project's own conformance suite against it, pinned to 0.1.16 by conformance/package-lock.json. conformance/baseline.yml lists the known failures and why each one fails (mostly the suite's own test fixtures, which a real server doesn't carry). It is read in both directions: a new failure fails the run, and so does an entry that now passes.

eval/questions.json is the DRAFT evaluation set: 30 questions across the three domains, each naming the variable and station a correct answer must use and a truth computed from the proxy at run time. It needs one reviewer per domain before it is relied on; the runner is not written yet.

This server is the ORACLE for the M9 port (mcpd, plan phase 7): its tool names, descriptions and answer shapes are the contract the port is replayed against, so change them deliberately.

Licence

Copyright (C) 2026 ICOS ERIC -- Carbon Portal.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See LICENSE.

The DATA this server serves are not covered by this licence: each answer carries the licence of its dataset (ICOS data are CC BY 4.0) and the citation to give with it.

Source: README.md at commit 4da9c57

Tools

8

list_datasets

List the ICOS datasets: one per data store, with domain (atmosphere, ocean, ecosystem), time and space coverage, licence and DOI.

Takes no parameters.

search_variables

Find variable ids in the ICOS catalogue by name, quantity or unit. The ids are what estimate and get_data take. Primary measurements come before their companions (standard deviation, value counts, flags).

Parameterstextrequiredlimitstoredomain

describe_variable

One variable in full: names, unit, which dataset, its coverage, how its quality flag is read, licence and DOI. For a multi-dimensional variable read through zarr (access 'zarr'), its axes with their labels, the slice /query serves (prescribed) and an xarray line for any other slice.

Parametersidrequired

estimate

How big a selection is -- rows, stations, time span -- without fetching it. Call this before get_data.

Parametersidrequiredendstartcruiselat_maxlat_minlon_maxlon_minstationapply_qcheight_maxheight_min

get_data

Observations for one variable, filtered by box, time, station, cruise, height and quality control. Returns at most max_rows rows as a table, the total, a download URL for the whole selection, and the citation the user must be given with any use of the data.

Parametersidrequiredendstartcruiselat_maxlat_minlon_maxlon_minstationapply_qcmax_rowsquestion+2 more

get_citation

How to cite a variable's data: the citation text, licence and DOI from its data passport, and -- for a selection (stations, a time window, a box) -- every data object it came from, in full. Data answers carry a short citation and only the COUNT of their sources; this lists them.

Parametersidrequiredendstartlat_maxlat_minlon_maxlon_minstation

aggregate

Statistics over a WHOLE selection, computed on the server: count, mean, min, max, sum and standard deviation of one variable, overall or per station, year, month or day. Use this for any average, total, range or trend instead of reading rows. Any size: a selection over 500,000 rows is split by time on the server and merged exactly. `std` is the POPULATION standard deviation (ddof 0). `sum` adds the values as stored, which is a total only for values that are themselves totals per row: summing a RATE (umol m-2 s-1 per half-hour, gC m-2 d-1 per day) or a concentration gives no physical quantity -- for a flux total multiply the mean by the period.

Parametersbyidrequiredendstartcruiselat_maxlat_minlon_maxlon_minstationapply_qcquestion+2 more

find_stations

The stations that carry a variable: id, name, position, sampling height, country, ecosystem -- near a point (sorted by distance), in a box, by name or by country. The ids are what estimate and get_data take as station=.

Parametersidrequiredtextlimitcountrylat_maxlat_minlon_maxlon_minnear_latnear_lonradius_km

Version history

2
  1. v0.3.0LatestNov 7, 2026
  2. v0.2.0Oct 30, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts