# well-data-mcp

MCP server for oil & gas and geothermal **well data worldwide**, pulled live from the
public services of state, provincial and national regulators and geological surveys.
No API keys, no accounts, no scraping of pages meant for people: these are the same
ArcGIS, WFS and query endpoints the agencies' own map viewers use.

It answers questions like "which wells does Fervo have at Cape Station", "every well
within 2 km of this pad", "look up API 30-025-36283", "Equinor's wellbores on the
Norwegian shelf" or "geothermal wells in the Netherlands" - and says plainly when a
country publishes nothing machine-readable.

![World map: countries with live well registries, countries covered through the pan-European GSEU compilation, and countries checked and found to have no public registry](docs/coverage-map.svg)

<!-- coverage:start (generated by `node scripts/coverage-table.js`) -->

## Coverage

### United States

| Key | Coverage | Agency | Via |
|---|---|---|---|
| `CA-OG` | California oil & gas wells | CalGEM (WellSTAR) | ArcGIS |
| `CA-GEO` | California geothermal wells | CalGEM (WellSTAR) | ArcGIS |
| `UT` | Utah oil & gas wells | Utah Division of Oil, Gas & Mining (DOGM) | ArcGIS |
| `UT-GEO` | Utah deep geothermal wells (incl. Fervo Cape Station, Utah FORGE) | Utah Division of Water Rights (DWRi) | ArcGIS |
| `UT-WLOG` | Utah drilled-well logs (every well drilled under a water-rights approval, incl. geothermal) | Utah Division of Water Rights (DWRi) | ArcGIS |
| `UT-THERMAL` | Utah thermal wells and springs (temperature + water chemistry) | Utah Geological Survey (UGS) | ArcGIS |
| `NM` | New Mexico oil & gas wells | NM OCD (EMNRD) | ArcGIS |
| `CO` | Colorado wells (API spots) | Colorado ECMC (via DNR GIS) | ArcGIS |
| `WY` | Wyoming oil & gas wells (WOGCC database snapshot) | Wyoming State Geological Survey (copy of the WOGCC well database) | ArcGIS |
| `WY-LIVE` | Wyoming wells - live WOGCC list (name, status, type) | Wyoming Oil and Gas Conservation Commission (WOGCC) Data Explorer | WFS |
| `MT` | Montana oil & gas wells | Montana Board of Oil & Gas Conservation (DNRC) | ArcGIS |
| `ID-OG` | Idaho oil & gas wells | Idaho Geological Survey | ArcGIS |
| `ID-GEO` | Idaho geothermal wells (low-temperature use, with water temperatures) | Idaho Department of Water Resources (IDWR) | ArcGIS |
| `OR-GEO` | Oregon geothermal wells and temperature-gradient holes (incl. Newberry) | Oregon DOGAMI (GTILO-2 compilation) | ArcGIS |
| `WA-OG` | Washington oil & gas wells | Washington DNR (Geology) | ArcGIS |
| `WA-GEO` | Washington geothermal well permits | Washington DNR (Geology) | ArcGIS |
| `AZ` | Arizona oil, gas, helium & geothermal wells | Arizona Oil & Gas Conservation Commission (hosted by ADEQ) | ArcGIS |
| `NV-GEO` | Nevada geothermal wells | NBMG (UNR) / NGDS | ArcGIS |
| `NV-OG` | Nevada oil & gas wells (compiled through 2013) | NBMG (UNR) | ArcGIS |
| `AK` | Alaska oil, gas & geothermal wells (incl. state offshore) | Alaska Oil and Gas Conservation Commission (via Alaska Division of Oil & Gas) | ArcGIS |
| `HI-GEO` | Hawaii geothermal wells (Puna) | Hawaii Statewide GIS Program | ArcGIS |
| `SD` | South Dakota oil & gas wells | South Dakota Geological Survey / DANR | ArcGIS |
| `ND` | North Dakota oil & gas wells | ND DMR Oil & Gas Division | ArcGIS |
| `TX` | Texas well locations (location + API only) | Texas RRC public GIS | ArcGIS |
| `TX-RRC` | Texas wellbores with operator, lease, field and county | Texas Railroad Commission (EWA wellbore query) | RRC query |
| `OK` | Oklahoma oil, gas & injection wells | Oklahoma Corporation Commission (RBDMS) | ArcGIS |
| `KS` | Kansas oil & gas wells | Kansas Geological Survey (KCC well data) | ArcGIS |
| `NE` | Nebraska oil & gas wells (API, name, location) | Nebraska Oil & Gas Conservation Commission | WFS |
| `MO` | Missouri oil & gas wells | Missouri DNR / Missouri Geological Survey | ArcGIS |
| `AR` | Arkansas oil & gas wells | Arkansas Oil and Gas Commission (via Arkansas GIS Office) | ArcGIS |
| `LA` | Louisiana oil & gas wells (incl. state waters) | Louisiana DENR Office of Conservation (SONRIS) | ArcGIS |
| `MS` | Mississippi oil & gas wells | Mississippi State Oil & Gas Board | WFS |
| `AL` | Alabama oil, gas & coalbed-methane wells | State Oil and Gas Board of Alabama (via Geological Survey of Alabama) | ArcGIS |
| `PA` | Pennsylvania oil & gas wells | Pennsylvania DEP Office of Oil and Gas Management | ArcGIS |
| `OH` | Ohio oil & gas wells | Ohio DNR Division of Oil & Gas Resources | ArcGIS |
| `WV` | West Virginia oil & gas wells | West Virginia DEP Office of Oil and Gas | ArcGIS |
| `KY` | Kentucky oil & gas wells | Kentucky Geological Survey | ArcGIS |
| `IL` | Illinois oil & gas wells | Illinois State Geological Survey (ILOIL) | ArcGIS |
| `IN` | Indiana oil & gas wells | Indiana DNR Division of Oil & Gas | ArcGIS |
| `MI` | Michigan oil, gas & mineral wells | Michigan EGLE (Oil, Gas, and Minerals Division) | ArcGIS |
| `NY` | New York oil, gas & solution-mining wells | New York DEC Division of Mineral Resources | ArcGIS |
| `TN` | Tennessee oil & gas wells | Tennessee Department of Environment and Conservation (TDEC) | ArcGIS |
| `VA` | Virginia gas & oil wells (active) | Virginia Energy, Division of Gas and Oil | ArcGIS |

### US federal offshore

| Key | Coverage | Agency | Via |
|---|---|---|---|
| `OCS-GOM` | US Gulf federal offshore wells (Outer Continental Shelf) | BOEM / BSEE (federal offshore) | ArcGIS |
| `OCS-PAC` | US Pacific federal offshore wells (Outer Continental Shelf) | BOEM / BSEE (federal offshore) | ArcGIS |
| `OCS-AK` | US Alaska federal offshore wells (Outer Continental Shelf) | BOEM / BSEE (federal offshore) | ArcGIS |
| `OCS-ATL` | US Atlantic federal offshore wells (Outer Continental Shelf) | BOEM / BSEE (federal offshore) | ArcGIS |

### Canada

| Key | Coverage | Agency | Via |
|---|---|---|---|
| `SK` | Saskatchewan oil & gas wells (vertical) | Saskatchewan Ministry of Energy and Resources | ArcGIS |
| `SK-HZ` | Saskatchewan oil & gas wells (horizontal / directional) | Saskatchewan Ministry of Energy and Resources | ArcGIS |
| `BC` | British Columbia oil & gas wells | BC Energy Regulator (BCER) | ArcGIS |
| `ON` | Ontario oil, gas, salt & storage wells (incl. Lake Erie) | Ontario Ministry of Natural Resources (Land Information Ontario) | ArcGIS |
| `NL-OFF` | Newfoundland & Labrador offshore wells | Newfoundland and Labrador Department of Industry, Energy and Technology | ArcGIS |
| `NS-OFF` | Nova Scotia offshore wells | Canada-Nova Scotia Offshore Energy Board directory (via NRCan) | ArcGIS |
| `NT` | Northwest Territories oil & gas wells | NWT Office of the Regulator of Oil and Gas Operations (OROGO) | ArcGIS |
| `YT` | Yukon oil & gas wells | Government of Yukon (Oil and Gas Resources Branch) | ArcGIS |
| `YT-GEO` | Yukon geothermal boreholes (temperature, gradient, heat flow) | Yukon Geological Survey | ArcGIS |

### Latin America & Caribbean

| Key | Coverage | Agency | Via |
|---|---|---|---|
| `BZ` | Belize exploration & production wells (onshore and offshore) | Government of Belize - petroleum data coverage map (Geology & Petroleum Department data) | ArcGIS |
| `MX` | Mexico oil & gas wells (onshore and offshore) | CNH well inventory as re-hosted by SEMARNAT | ArcGIS |
| `CO-EPIS` | Colombia oil & gas wells | Servicio Geológico Colombiano (EPIS) | ArcGIS |
| `BR-ANP` | Brazil oil & gas wells (onshore and offshore, incl. pre-salt) | ANP - Agência Nacional do Petróleo, Gás Natural e Biocombustíveis | WFS |
| `PE` | Peru oil & gas wells | PERUPETRO | WFS |
| `AR-CONV` | Argentina oil & gas wells - conventional | Secretaría de Energía de la Nación (Argentina) | WFS (FES) |
| `AR-SHALE` | Argentina oil & gas wells - shale (Vaca Muerta...) | Secretaría de Energía de la Nación (Argentina) | WFS (FES) |
| `AR-TIGHT` | Argentina oil & gas wells - tight | Secretaría de Energía de la Nación (Argentina) | WFS (FES) |
| `AR-OTHER` | Argentina oil & gas wells - resource type not reported | Secretaría de Energía de la Nación (Argentina) | WFS (FES) |

### Europe

| Key | Coverage | Agency | Via |
|---|---|---|---|
| `FR-BSS` | France boreholes incl. overseas departments (Guadeloupe/Bouillante, Martinique, Réunion...) | BRGM - Banque du Sous-Sol (BSS) | WFS (FES) |
| `NO-SODIR` | Norway offshore wellbores (all: exploration, development, other) | Sodir - Norwegian Offshore Directorate (FactMaps) | ArcGIS |
| `GB-NSTA-OFF` | UK offshore wellbores (UKCS) | North Sea Transition Authority (NSTA) | ArcGIS |
| `GB-NSTA-ON` | England onshore petroleum wells | North Sea Transition Authority (NSTA) | ArcGIS |
| `GB-BGS` | Great Britain borehole index (all onshore drilling, incl. deep geothermal) | British Geological Survey (Single Onshore Borehole Index) | ArcGIS |
| `NL-NLOG` | Netherlands deep boreholes (oil, gas, geothermal, salt, storage; onshore and offshore) | TNO / NLOG (Dutch Oil and Gas Portal) | WFS |
| `IS-OS` | Iceland borehole registry (geothermal production, reinjection, gradient wells...) | Orkustofnun (National Energy Authority) via the national geoportal | WFS |
| `DE-LBEG` | Germany deep wells (hydrocarbon, storage, salt, geothermal) - North German Basin, North Sea, Upper Rhine | LBEG - Landesamt für Bergbau, Energie und Geologie (NIBIS) | WFS (FES) |
| `PL-PGI` | Poland borehole database (all purposes, incl. geothermal) | Polish Geological Institute (PGI-PIB, CBDG) | ArcGIS |
| `IE-OFF` | Ireland offshore petroleum wells | Petroleum Affairs Division (Department of the Environment, Climate and Communications) | ArcGIS |
| `IE-ON` | Ireland onshore petroleum wells | Petroleum Affairs Division (Department of the Environment, Climate and Communications) | ArcGIS |
| `DK-GEUS` | Denmark released exploration wells (onshore and offshore) | GEUS - Geological Survey of Denmark and Greenland (Samba) | WFS (FES) |
| `EU-GSEU` | Pan-European deep boreholes with bottom-hole temperatures (25 national surveys) | Geological Service for Europe (GSEU) via EGDI | WFS (FES) |

### Africa & Asia

| Key | Coverage | Agency | Via |
|---|---|---|---|
| `ID-MIGAS` | Indonesia oil & gas wells | Directorate General of Oil and Gas (Ditjen Migas), Ministry of Energy and Mineral Resources - MDR | ArcGIS |
| `ZA-PASA` | South Africa petroleum wells (mostly offshore: Bredasdorp, Orange...) | Petroleum Agency SA (PASA) | ArcGIS |
| `MZ-INP` | Mozambique exploration & production wells | Instituto Nacional de Petróleo (INP) | ArcGIS |
| `KE-PET` | Kenya petroleum exploration wells (unofficial copy of the ministry map) | State Department for Petroleum map, re-hosted on ArcGIS Online by a third-party account | ArcGIS |

### Oceania

| Key | Coverage | Agency | Via |
|---|---|---|---|
| `NZ-PET` | New Zealand petroleum wells (nationwide, incl. offshore) | NZ Petroleum & Minerals (NZP&M) | ArcGIS |
| `NZ-WAIKATO` | Waikato geothermal wells (Taupō Volcanic Zone, incl. deep production wells) | Waikato Regional Council (National Wells Database) | ArcGIS |
| `NZ-BOP` | Bay of Plenty geothermal bores (Rotorua, Tauranga...) | Bay of Plenty Regional Council | ArcGIS |
| `AU-GA` | Australia national borehole database (petroleum, coal-seam gas, geothermal, stratigraphic) | Geoscience Australia | WFS |
| `AU-SA-PET` | South Australia petroleum wells (Cooper/Eromanga...) | Government of South Australia, Department for Energy and Mining (SARIG) | WFS |
| `AU-SA-GEO` | South Australia geothermal wells (incl. Habanero) | Government of South Australia, Department for Energy and Mining (SARIG) | WFS |
| `AU-QLD-PET` | Queensland petroleum wells | Geological Survey of Queensland | ArcGIS |
| `AU-QLD-CSG` | Queensland coal-seam-gas wells | Geological Survey of Queensland | ArcGIS |
| `AU-WA` | Western Australia onshore petroleum wells | WA Department of Energy, Mines, Industry Regulation and Safety (DMIRS-025) | ArcGIS |

### No public registry found

- **Guatemala** - No official registry. The Energy & Mines ministry (mem.gob.gt) and the open-data portal sit behind a browser challenge scripts cannot pass; the national spatial data infrastructure (IDEG/SEGEPLAN) WFS has no hydrocarbon or geothermal layers. Geothermal well data (Zunil, Amatitlán) is operator-held. Project level: search_gem_projects.
- **Eastern Caribbean geothermal islands** - Dominica, St Kitts & Nevis, Montserrat, St Lucia, Grenada, St Vincent: no machine-readable well data found (reports and PDF tables only; the regional CHARIM GeoNode is offline). Guadeloupe and Martinique boreholes are in FR-BSS. Project level: search_gem_projects.
- **Central American geothermal** - El Salvador, Honduras, Nicaragua, Costa Rica, Panama: no public geothermal well service found (Ahuachapán, Berlín, Momotombo, San Jacinto-Tizate, Miravalles are operator-held). Project level: search_gem_projects.
- **Mexico (geothermal)** - CFE publishes no geothermal well data (Cerro Prieto, Los Azufres, Los Humeros). Oil & gas wells are in MX (a 2024 snapshot). The former CNH map (mapa.hidrocarburos.gob.mx) is offline.
- **Ecuador** - The hydrocarbon regulator's geoportal requires a login; well data is released only by formal request.
- **Bolivia** - GeoBolivia (geo.gob.bo) is unreachable; no other official well service found.
- **Trinidad & Tobago** - The Ministry of Energy publishes only PDF data-package listings for bid rounds; no well service.
- **Chile (geothermal)** - No geothermal well service found (Cerro Pabellón is operator-held); open-data and ministry GIS searches return nothing.
- **Alberta and Manitoba** - Not yet supported: Alberta's AER publishes its well list (ST37) only as a 565 MB monthly bulk download, and its live map layer covers abandoned wells only and blocks text search. Manitoba publishes a 0.7 MB shapefile download (wells.zip) but no working query service.
- **Turkey** - MTA's earth-science viewer exposes no data endpoint; no public well service found. Some Turkish boreholes may appear in EU-GSEU.
- **Hungary, Austria, Croatia, Romania, Greece, Portugal (incl. Azores), Spain** - No national keyless well service found (or only names and basins, as with Spain's IGME layer). Use EU-GSEU, which carries deep boreholes - many geothermal, with bottom-hole temperatures - from these countries' surveys.
- **Italy** - Not yet supported: the ministry (UNMIG) publishes producing hydrocarbon wells only as CSV/KML downloads, without dates or depths; historic wells (ViDEPI) are PDF logs. Italian deep boreholes appear in EU-GSEU.
- **Switzerland** - Not yet supported: swisstopo publishes wells deeper than 500 m (incl. Basel-1 and other geothermal wells) through the geo.admin.ch API, which needs its own adapter. Swiss boreholes appear in EU-GSEU.
- **Kenya** - No official machine-readable registry. Petroleum exploration wells: KE-PET, an unofficial copy of the State Department for Petroleum's map. Geothermal wells (Olkaria, Menengai) are held by KenGen and GDC, whose GIS hosts are not public; some Olkaria research data is in the DOE GDR (search_geothermal_datasets); heat flow and temperature gradients across the Kenya Rift: search_heat_flow; plant level: search_gem_projects.
- **Namibia** - No public well registry. The Ministry of Mines and Energy's petroleum licence layers (Landfolio cadastre) need a token, and NAMCOR sells E&P data (incl. the offshore Orange Basin discoveries). Heat flow: search_heat_flow; field level: search_gem_projects.
- **Uganda, Ghana, Nigeria, Ethiopia, Tanzania, Rwanda, Senegal, Egypt** - No keyless official well service found: Uganda's and Ghana's petroleum ArcGIS services require tokens, Egypt's upstream gateway requires a login, and the others publish HTML/PDF or nothing. Heat flow: search_heat_flow; field level: search_gem_projects.
- **New Zealand (national geothermal database)** - GNS Science's GGW database is a click-through web app whose terms allow internal use only (no publishing), so it is not used. Geothermal wells come from regional councils instead: NZ-WAIKATO and NZ-BOP. NZP&M petroleum wells are in NZ-PET.
- **Victoria, New South Wales, Northern Territory, Tasmania** - Not yet wired: Victoria and NSW publish petroleum wells via WFS, the NT as a CSV download, Tasmania inside a mixed borehole layer. AU-GA covers these states from the national database.
- **Japan** - Not yet supported: the Geological Survey of Japan publishes borehole temperatures (GT-4) only as static GeoJSON files; no well registry service found.
- **Philippines, India, Malaysia, Papua New Guinea, Timor-Leste** - No keyless well service found: India's national data repository needs a login, Timor-Leste's is a virtual data room, and the others publish PDFs or nothing.

<!-- coverage:end -->

## Tools

| Tool | What it does |
|---|---|
| `list_sources` | Coverage index; pass `country`, `state` or `source` for endpoints, filters, id types, caveats and licences, plus notes on places with no registry |
| `search_wells` | Search by operator, well name, county/area, field, status or type in one source, a state, a country, or everywhere. `count_only` sizes a query first |
| `get_well` | One well's full raw record by identifier. US API numbers in any format are routed to the right state by their 2-digit API prefix; UWIs, wellbore names and agency codes work with `country` or `source` |
| `wells_near` | Every well within a radius of a point. Only sources whose coverage area overlaps the circle are asked, so it works anywhere without picking a source |
| `list_operators` | The exact operator strings a source uses (`'Fervo Energy Company'`, `'Equinor Energy AS'`...) |
| `raw_query` | Raw SQL-92 `where` (ArcGIS sources) or CQL (GeoServer WFS sources) for filters the normalized search doesn't cover - dates, depths, cumulative production |
| `search_geothermal_datasets` | DOE geothermal datasets: text search via OSTI, or - given a latitude/longitude - the Geothermal Data Repository catalog's footprints, returning datasets that cover the place with direct file links (Cape Station, Utah FORGE, Newberry...) |
| `search_heat_flow` | Bundled IHFC Global Heat Flow Database (offline): ~91,000 heat-flow measurements worldwide with temperature gradient, thermal conductivity, depth and purpose - geothermal screening anywhere, with summary statistics for a radius |
| `search_gem_projects` | Bundled Global Energy Monitor trackers (offline): geothermal power units and oil & gas fields worldwide - the fallback where no well registry exists |

### What a record looks like

Every source is mapped to the same core fields, then keeps its own extras
(temperatures, production, formation, links to scanned well files...):

`source, country, state, api, wellName, operator, status, wellType, field, county,
latitude, longitude, spudDate` plus whatever else the source publishes
(`completionDate`, `depthMD`, `depthTVD`, `waterDepth`, `bottomHoleTempC`...).

- `api` holds the source's well identifier: a US API number, Canadian UWI, Norwegian
  wellbore name, BSS code and so on. `list_sources` says which, per source.
- Coordinates are WGS84 decimal degrees, taken from the server-reprojected geometry
  (attribute coordinates are often NAD27, ED50 or sign-flipped).
- Every `*Date` field is an ISO `YYYY-MM-DD` string or null, whatever the source
  stores (epoch milliseconds, `MM/DD/YYYY`, `DD.MM.YYYY`, `16-NOV-2017`...).
- Units are the agency's: most US sources use feet, most others metres. Sources that
  mix units carry a `depthUnit` field.
- A source that cannot apply a filter you asked for is skipped with a note rather than
  returning unfiltered results.

## Run / register

Requires **Node 18+** (native `fetch`, top-level `await`); developed on Node 22.

```
npm install
npm test               # offline unit tests
npm run smoke          # live: search + id lookup + radius search against every source
npm run smoke -- NO UT # just some sources (matches key, country or state)
claude mcp add --scope user well-data -- node <abs-path>/src/index.js
```

`claude mcp add` stores that absolute path in `~/.claude.json`; moving the project
folder breaks the registration until you run it again. Any other MCP client can launch
`node src/index.js` over stdio the same way. `package.json`'s `bin` entry means
`npx -y well-data-mcp` will work if the package is ever published to npm (it isn't yet).

`node scripts/call-tool.js <tool> '<json args>'` calls one tool over stdio, the way an
MCP client would - handy for trying a query from a terminal.

## Adding a source

Each source is one object in `src/sources/<region>.js`: endpoint, a map from the
normalized filters to the layer's own field names, a `normalize(attrs, geometry)`
function, a rough `extent`, and a `probe` filter known to return hits (the smoke test
uses it). The protocol is a `kind`:

- `arcgis` (default) - any ArcGIS MapServer/FeatureServer layer. Find layers with
  `…/rest/services?f=json`, then a layer's fields with `…/MapServer/<id>?f=json`.
  Options cover common server quirks: `noPaging`, `noReproject`, `apiNumeric`,
  `dedupeBy`, `baseWhere`, `headers`, `outFields` (see `src/providers/arcgis.js`).
- `wfs` - OGC WFS 2.0 with GeoJSON output: `dialect: "cql"` for GeoServer,
  `dialect: "fes"` for MapServer, deegree and others that ignore CQL.
- `rrc-ewa` - the Texas RRC wellbore query (operator, lease and field for Texas).

Run `npm run smoke -- <KEY>` until search, id and radius checks pass, then
`node scripts/coverage-table.js` to refresh the tables above.

## Data licences and attribution

Each agency's terms apply to its data; `list_sources` shows the licence where the
agency states one. Notably:

- **Alabama** (State Oil and Gas Board): the terms forbid redistributing the data to
  third parties without permission. Query it live; don't republish it.
- **Norway** (Sodir): Norwegian Licence for Open Government Data (NLOD).
- **UK** (NSTA): NSTA Open User Licence. **Ontario / Canada (NRCan)**: Open Government
  Licence. **Argentina** (Secretaría de Energía): CC BY 4.0.
- **DOE Geothermal Data Repository** datasets: mostly CC BY 4.0 (each result says).
- **IHFC Global Heat Flow Database** bundled in `data/`: CC BY 4.0 - cite it as given in
  every `search_heat_flow` response (see `data/ATTRIBUTION.md`). Refresh by downloading a
  new release from GFZ Data Services and running `python scripts/convert-ihfc.py <zip>`.
- **Global Energy Monitor** trackers bundled in `data/`: CC BY 4.0 - credit "Global
  Energy Monitor" (see `data/ATTRIBUTION.md`). Refresh by downloading a new release
  from globalenergymonitor.org/download-data, `pip install -r scripts/requirements.txt`,
  then `python scripts/convert-gem.py <dir>`.

## Source

https://github.com/Wickemu/well-data-mcp - MIT licensed (the code; data licences above).