Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Kanysh Basic > Assess my registered folder, then check the imported model for issues."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An AI copilot for calculations on geological models, alongside Petrel and RMS. Open an exported model, ask for a check or scenario in your chat, and receive a report with assumptions and independent numerical checks.
Kanysh Basic is an MCP server for subsurface modeling + local web viewer. MCP is the connection that lets your chat use the calculation tools. The chat requests work; the viewer displays projects, revisions, reports and 3D scenes. Numerical work runs locally. Your chat client controls which messages and tool results reach its AI provider.
Windows: install the Claude Desktop extension in three steps.
Download the release .mcpb → double-click → Install → choose your exported model folder.
No terminal or WSL is needed for static workflows. A client supporting MCPB 0.4's UV
runtime and internet access for the initial dependency download are required.
Russian installation guide.
Native Windows installation in Claude Desktop is verified: the .mcpb installs by
double-click and the tools run on a real exported model (Volve test);
issues found during that check were fixed in 0.2.0.dev5/dev6 (CHANGELOG).
macOS/Linux source installation and first result.
Public Norne geometry and porosity: 44,927 active cells. Statoil / OPM, ODbL-1.0 / DbCL-1.0. Demo fluid parameters are explicit benchmark assumptions, not a field reserves estimate.
Install on Windows: follow the three-step extension guide.
Keep %LOCALAPPDATA%\kanysh-basic for results and choose your real model folder.
Open Norne demo in the viewer to inspect saved public geometry and reports. This does not run a new calculation.
In Claude, ask: “Use Kanysh Basic's start tool, then assess my registered model folder.” Confirm that actual tool results appear. Add another folder with Add folder in the viewer.
Confirm file-derived proposals, then ask for QC or a scenario. Save the report and XLSX/PDF exports. Use the same results home when reconnecting.
For macOS/Linux or IT source installation, install uv, open the source folder and run:
uv python install 3.12
uv sync --frozen --no-dev --extra ui --extra viewer --python 3.12
uv run --no-sync kanysh-basic --home "$HOME/.kanysh-basic" setupClose Claude clients before setup. It backs up configuration and opens the viewer. The default install uses CPU PyTorch; NVIDIA is an explicit GPU option. WSL/Linux is only needed for optional OPM Flow deck runs. The source-only extension includes no Python environment; its host installs dependencies. Acceptance with chat clients other than Claude Desktop remains NOT RUN.
Related MCP server: OSDU MCP Server
Extension | Default results home on Windows | Runtime |
|
| CPU |
|
| CUDA 12.6 on Windows/Linux; CPU on macOS |
Both extensions can be installed alongside each other. Keep their separate default
homes. The GPU edition's first installation downloads approximately 2.5 GB; allow
additional disk space for dependencies. It reports the detected GPU/CUDA version or
falls back to CPU with a warning. Calculations retain their existing CPU default:
request prefer_gpu with explicit CPU fallback, or require_gpu, for supported
operations. CUDA is verified on an RTX 3080 Ti Laptop: GPU regional/corner-point volumes
pass the mandatory CPU comparison. MPS acceleration is not implemented.
The host installs Python and dependencies before running the MCP entry point.
Fast MCP initialization cannot prevent a timeout during that host-controlled download.
After Python starts, tool discovery
is immediate while local services initialize. A STARTING response includes a retry
interval; FAILED includes the log path and keeps the MCP connection available.
The viewer and startup-status.json show the actual results folder, including any
Windows MSIX LocalAppData virtualization. Startup and build evidence.
Build either extension from a prepared source environment (Node/npm and uv required):
uv run --no-sync python scripts/build_mcpb.py --variant cpu
uv run --no-sync python scripts/build_mcpb.py --variant gpuBoth commands use the official mcpb validate / mcpb pack CLI and a separate checked-in
UV lock. Add --refresh-lock only when intentionally updating dependency resolution.
Task | Example message |
Check a model | “Assess my registered folder, tell me what is missing, then check the imported model. Show severity and affected IJK cells.” |
Calculate regional volumes | “Prepare oil and free-gas volumes by region. Ask for contacts, Bo/Bg and saturation assumptions, and calculate after I confirm them.” |
Reconcile with Petrel/RMS | “Compare the regional volumes with my Petrel CSV. Explain differences in units, definitions and assumptions without changing inputs.” |
Explore sensitivity | “Build a tornado analysis for the parameter ranges I provide. Keep the baseline and assumptions in the report.” |
Compare model versions | “Compare these two revisions with the same IJK grid. Show changed cells and their regional pore-volume impact.” |
The agent asks for required engineering inputs. Values found in files are proposals with source evidence until you confirm them. Missing constants are not guessed. Independent numerical PASS still requires geological review.
Export exchange files from Petrel/RMS; native project databases are unsupported. For a first grid check, prefer ECLIPSE ASCII DATA/GRDECL with its INCLUDE files, geometry, active mask and properties. Export checklist.
Open a report's result page to inspect its assumptions, independent checks and
regional tables. Ask for Excel/PDF export and use the resulting file links to save
it. A finished job can still have QC issues. NOT RUN means a check was not performed.
Result/status guide.
The accepted workflows also include exchanged surfaces/wells/tops/polygons, LAS/model comparison, explicit saturation-height functions and correlated scalar Monte Carlo. Capabilities and evidence · Norne recording recipe and exact numbers.
Real-data check: the public Equinor Volve model (680,400 cells) was imported from its
ECLIPSE GRID/INIT output, checked, and volumed by region; pore volume matches ECLIPSE PORV
except where the deck applies explicit history-match multipliers. Volve results and gaps found.
simulation_deck_run runs your own ECLIPSE-format .DATA deck and its INCLUDE files in
OPM Flow exactly as supplied: no deck generation or default values. Executors are native
Linux or, on Windows, a dedicated WSL2 distribution kanysh-opm (your own distributions
and Docker are not used). Set it up once:
kanysh-basic setup-opmIt installs OPM Flow, pins the version and binary hash and self-tests on SPE1. Without it,
deck runs are refused with SIMULATOR_UNAVAILABLE and install steps; static workflows are
unaffected. Results include summary vectors (Parquet), PRT/DBG logs and an optional comparison
with your reference SMSPEC. On Volve, OPM Flow matched ECLIPSE initial FOIP exactly and field
pressure within 0.46 % after three documented deck edits.
eclipse_import streams ASCII DATA/GRDECL, binary EGRID and legacy .GRID with INIT/GRDECL
properties; a synthetic 200 million-cell corner-point profile passes import, QC, volumes,
tornado and scene export on CPU. The legacy XTGeo/ROFF import retains its 2 million-cell cap.
Scaling implementation · Measured limits and benchmarks.
Unsupported DATA keywords are listed in the import report. Decks with ADDZCORN are refused
by the ASCII importer (import the simulator's GRID/EGRID output instead). SWATINIT is not equilibrium SWAT.
Bo/Bg, contacts, saturations, units and CRS/datum need an explicit basis. STOIIP/GIIP are initial volumes, not recoverable reserves or production forecasts.
Polygon selection keeps whole cells by mean corner XY; saturation-height functions use mean corner Z. Scalar uncertainty is not spatial simulation.
CPU blocks support resource-bounded process pools. Regional/imported corner-point volumes also support float64 CUDA with mandatory CPU comparison. Viewer previews are bounded; calculation inputs are not downsampled.
OPM Flow runs the deck as given; it may reject keywords ECLIPSE tolerates. parsing_strictness=low
lists ignored keywords and reports PASS_WITH_IGNORED_KEYWORDS. Decks referencing files outside
the INCLUDE closure (RESTART, IMPORT, GDFILE, ...) are refused. No MPI runs yet.
The web app is an English-language viewer. Calculations run through the connected
chat/MCP, CLI or REST. Gradio/Plotly are optional [ui] dependencies; [viewer] enables scenes.
Kanysh Basic contains the accepted workflows above. Further modelling development belongs to Kanysh Advanced: roadmap. Local Advanced experiments are excluded from Basic GitHub publication, packages and production MCP profiles.
MCP/CLI/REST setup · IT setup reference · CONTRIBUTING · Publication audit. CI targets Windows/Ubuntu/macOS with ruff and CPU pytest, excluding gpu/opm/external tests.
The Python namespace, data-format IDs, MCP resource URIs and OPENSUBSURFACE_*
environment names retain their existing identifiers for compatibility. The package
and public CLI are kanysh-basic; opensubsurface remains a CLI compatibility alias.
This is a development release (0.2.0.dev6); external acceptance is separate.
Application source: Apache-2.0. Norne data: ODbL/DbCL with upstream notices retained. Dependencies have separate licences: THIRD_PARTY.
Read one immutable artifact {id, revision}: metadata, summary, file list and checks. Read-only; ids/revisions come from project_inspect or earlier tool results.
Inputs: request (required).
Prepare static volumes plan. Missing scientific inputs return NEEDS_INPUT/questions without compute. READY plan pins input bytes, assumptions and runtime. No numerical jobs run.
Inputs: request (required).
Execute a READY plan as a durable workflow, validate every output and export report. Returns run_id/job_id; same default key reuses the run. Explicit resume_run is a workflow snapshot ref.
Inputs: request (required).
Compact run state, errors, checkpoint and output/report refs. Use this after reconnecting; do not infer success from tool-call completion.
Inputs: request (required).
Configured compute targets (local CPU, CUDA state) and device_matrix: which operations support prefer_gpu/require_gpu. Read-only.
Inputs: request (required).
Import an uploaded CSV/LAS (source_upload upload_id) as a dataset of an explicit kind: collars, trajectory, markers, surfaces, orientations, production, las. CRS, vertical datum and column units are declared by the user, never inferred. Returns job_id then a dataset artifact.
Inputs: request (required).
dataset_import_snapshot
Inputs: request (required).
dataset_validate
Inputs: request (required).
development_rank
Inputs: request (required).
Read-only startup/runtime diagnostics, available even while starting: stage/substage/waiting_for, startup.log tail, versions, CUDA state (if probed), viewer URL/port and log tail. No secrets or environment values.
Inputs: request (required).
Import static ECLIPSE DATA/GRDECL from an owner folder, recursively resolving revision-checked relative INCLUDE inside it. Streams COORD/ZCORN to block geometry and preserves ACTNUM/PORO/NTG/PERMX/SWAT/FIPNUM/SATNUM/EQLNUM; applies explicit EQUALS/MULTIPLY/COPY/ADD/BOX/ENDBOX. Returns job_id then properties with import_report.json listing every unsupported keyword and NOT RUN scientific checks. CRS/datum/units and any missing-property defaults require explicit user input. Does not perform equilibrium or MINPV/pinch/simulator initialization.
Inputs: request (required).
ensemble_compare
Inputs: request (required).
ensemble_plan
Inputs: request (required).
ensemble_run
Inputs: request (required).
fault_create
Inputs: request (required).
Assess a registered folder with bounded header reads: candidate roles, missing inputs, available workflows and file/line parameter proposals. Proposals MUST be confirmed with the user before any plan/calculation. No scientific calculation or automatic PVT/contact choice. Includes export instructions resource.
Inputs: request (required).
Import Petrel/RMS exchanged surfaces (IRAP ASCII/binary, ZMAP+, CPS-3 ASCII), RMS well ASCII or explicitly mapped Petrel ASCII trajectories/tops/polygons using XTGeo. User declares units/Z direction/CRS/datum and ASCII mappings; no automatic coordinate or survey interpretation. CPS-3 requires explicit sample order/Y direction. Returns dataset with source hash, canonical Parquet and report; optional trajectory locates MD-only tops for scene display.
Inputs: request (required).
Import a revision-pinned model manifest from a registered source: Cartesian NPY/GRDECL properties, or cornerpoint.xtgeo.v1 geometry (GRDECL/EGRID/ROFF with COORD/ZCORN, ACTNUM and explicit property declarations). XTGeo geometry import needs full RAM and <=2M cells; later calculations use bounded CPU blocks. No native Petrel projects. Returns job_id.
Inputs: request (required).
horizon_convert_domain
Inputs: request (required).
interpretation_save
Inputs: request (required).
Request cancellation of a queued or running job (job_id). Stops the worker and any child simulator; already published artifacts are kept. Check job_status afterwards.
Inputs: request (required).
Tail of worker stdout/stderr, workflow node log and stage events; for calculation_run also each child job's status and worker tail. Local evidence only; no secrets.
Inputs: request (required).
Compact job state: id, status, stage, progress 0..1, eta_s, error, result ref, payload_hash. verbose=true returns the full record (payload, attempts, events). Numbers are in the result artifact (artifact_inspect).
Inputs: request (required).
Define a regular geological model: GemPy or explicitly horizontal layers.
Inputs: request (required).
Compare two immutable same-IJK model revisions with explicit tolerances: changed cells/properties, IJK CSV and region GRV/PV/HCPV impacts. Independently verifies geometry volumes. No contact or Bo is inferred, so no STOIIP impact is invented. Rejects differing topology/coordinate metadata.
Inputs: request (required).
Numerical QC of an immutable model: trilinear signed/degenerate/twisted geometry, property ranges, NTG/PORO consistency, active zero pore volume, IJK six-neighbour clusters and regional summaries. Returns a durable report with severity/IJK CSV witnesses and independent volume/cluster accounting. Connectivity is topological, not flow connectivity. Geological fitness remains specialist review.
Inputs: request (required).
Verify immutable plan input hashes, runtime compatibility and current resource preflight; original folders need not remain connected after snapshots.
Inputs: request (required).
Create a project with explicit CRS, vertical datum and metric units.
Inputs: request (required).
One project: its record, every immutable artifact (id, revision, kind) and its jobs. Read-only; use artifact_inspect for one artifact's content.
Inputs: request (required).
List projects in this results home: id, name, CRS, vertical datum, length unit, creation time. Read-only.
Inputs: request (required).
properties_assign
Inputs: request (required).
properties_krige
Inputs: request (required).
properties_reference
Inputs: request (required).
properties_simulate
Inputs: request (required).
Explicit, user-confirmed regional OWC/GOC oil/free-gas scenarios with Bo/Bg and residual phase saturations; optional polygon whole-cell corner-mean selection and saturation-height table or Leverett J with all parameters from user. Returns report with separate STOIIP/GIIP and independent determinant/ConvexHull integral checks. Positive-up metric Z. No field constants or saturation equilibrium are inferred.
Inputs: request (required).
Export evidence-bound HTML/Markdown/JSON/CSV/PNG for calculation run_id, including failed/partial runs. Returns job_id. Missing evidence cannot yield PASS.
Inputs: request (required).
Get report PNG (native image in MCP) and resource/download references. Does not return whole model arrays.
Inputs: request (required).
Export immutable analysis/calculation reports to XLSX (scenario/region sheets) and PDF (tables, assumptions, source tornado/S-curve plots). Independently checks every workbook value and PDF provenance/status text. Source NOT RUN/FAIL remains visible; export PASS is serialization only. Explicit PDF table row limit; full tables in XLSX/JSON.
Inputs: request (required).
Independent checks in isolated worker; returns job_id and then validation artifact. PASS applies only to required supported numerical checks, not geological fitness.
Inputs: request (required).
scenarios_compare
Inputs: request (required).
scenarios_run
Inputs: request (required).
Publish persisted scene as interactive PyVista/trame HTML, PNG and scene.json in an isolated worker. Bounded preview; explicit stride/cell_range for large grids. Returns job_id.
Inputs: request (required).
Current persisted scene settings of a project (visibility, opacity, field, selection, stride, slices) as set by scene_show. Read-only.
Inputs: request (required).
Persist artifact visibility, opacity, property, selection, stride and seismic slice options in the unified scene. TWT overlay needs explicit velocity and origin. Does not start a viewer job.
Inputs: request (required).
seismic_attribute
Inputs: request (required).
seismic_generate
Inputs: request (required).
seismic_import
Inputs: request (required).
seismic_inspect
Inputs: request (required).
seismic_slice
Inputs: request (required).
Stream a revision-pinned SEG-Y from an owner source into float32 Zarr tiles, bypassing upload limits. Sorted regular zero-offset poststack, IBM/IEEE float32 only; no amplitude downsampling. Explicit CRS/datum/units/header mapping. Returns job_id.
Inputs: request (required).
One-at-a-time regional sensitivity using explicit user low/high values and override/multiplier meanings. All variants are independently checked; report and tornado PNG preserve failures and baseline assumptions. No probability is inferred from deterministic bounds. Explicit cell-scenario work budget.
Inputs: request (required).
simulation_case_create
Inputs: request (required).
simulation_compare
Inputs: request (required).
Run the user's own ECLIPSE-format .DATA deck (with its INCLUDE files) in OPM Flow, exactly as supplied: no deck generation or defaults. Linux natively, Windows via the 'kanysh-opm' WSL2 distribution set up by kanysh-basic setup-opm; SIMULATOR_UNAVAILABLE explains setup when absent. Returns job_id; results: summary (Parquet), SMSPEC/UNSMRY, PRT/DBG logs, field totals; optional comparison with a user reference SMSPEC (e.g. ECLIPSE) at an explicit tolerance. Cancellable.
Inputs: request (required).
simulation_results
Inputs: request (required).
simulation_snapshot
Inputs: request (required).
Run real OPM Flow; returns a job error when the solver is absent.
Inputs: request (required).
simulation_validate
Inputs: request (required).
Read bounded CSV headers/sample rows or a Cartesian/corner-point JSON model manifest with metadata/header and RAM checks. No CRS/units inference; source text is untrusted data.
Inputs: request (required).
Local folders authorized by the owner. Folders cannot be added or removed through tools.
Inputs: request (required).
Metadata of one folder: CSV/LAS/SEG-Y/NPY/JSON files and subfolders, without reading contents. The next page requires listing_revision.
Inputs: request (required).
Copy a verified snapshot of a CSV/LAS/SEG-Y file from an authorized folder into the project (up to 256 MiB). Requires file_revision from source_scan; then dataset_import/seismic_import.
Inputs: request (required).
Начать / Start: first-connection onboarding, demo Norne and owner folder registration instructions. No calculation or download.
Inputs: request (required).
Seeded regional Monte Carlo with explicit bounded marginal distributions and Gaussian-copula correlation matrix. Independently checks every valid realization and P90/P50/P10 linear-rank statistics; publishes all attempted draws CSV, S-curve PNG, failures and empirical marginal correlations. No hidden resampling/clipping or spatial-realization claim. Conditional percentiles are labelled if draws fail.
Inputs: request (required).
variogram_fit
Inputs: request (required).
Recompute user-confirmed regional scenarios and compare against a revision-checked Petrel/RMS volume CSV. User maps region_id/metric/value/unit columns and states metric/region definitions. Report differences, unsupported rows as NOT RUN and evidence-labelled possible causes (contact, Bo, NTG clipping, inactive cells, region definition); never auto-calibrate inputs.
Inputs: request (required).
Initial oil in place (not recoverable reserves) with fractional OWC; returns job_id.
Inputs: request (required).
Compare immutable model PORO/NTG against explicitly mapped original LAS curves along imported XYZ/MD surveys. User confirms curve units, maximum survey gap and shared-boundary policy. Reports model-minus-LAS error statistics by well/region and sample CSV with IJK; null/out-of-survey/out-of-grid samples are explicit exclusions. Independent point-containment and RMSE checks. This is point comparison, not automatic log upscaling or calibration.
Inputs: request (required).
workflow_cancel
Inputs: request (required).
workflow_run
Inputs: request (required).
workflow_save
Inputs: request (required).
workflow_status
Inputs: request (required).
workflow_validate
Inputs: request (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 73 tools
The set has many overlapping clusters: simulation_submit, simulation_deck_run, simulation_case_create, simulation_validate, simulation_results, simulation_compare, and simulation_snapshot are hard to distinguish without reading deep descriptions, and several import tools (dataset_import, dataset_import_snapshot, geodata_import, eclipse_import, grid_import, seismic_import, seismic_source_import) have blurred boundaries. Many tools also have descriptions that are just the tool name (properties_reference, fault_create, properties_assign, scenarios_run, seismic_generate), forcing the agent to guess.
Most names are snake_case, but the convention mixes verb_noun (create, list, inspect, import), noun_verb (fault_create, properties_assign, volumetrics_calculate, seismic_generate), and bare nouns (diagnostics, start, properties_reference). It remains readable, but the inconsistent ordering and vague standalone names reduce predictability.
At 73 tools, the surface is far beyond a well-scoped set and includes many highly specialized operations plus multiple workflow/job/scene management tools. The breadth is excessive even for a broad reservoir-modeling platform, making discovery and correct selection difficult.
The surface covers import, QC, model building, property modeling, volumetrics, simulation, uncertainty, ensembles, export, visualization, and job/project management, so core domain workflows are broadly represented. Gaps are mostly lifecycle operations such as delete/update for projects, workflows, or artifacts, and some tools lack enough detail to assess their coverage.
Well log analysis: import LAS/DLIS, run petrophysics, build log plots and reports in the browser
Connect your AI assistant to Blender for 3D modeling, Geometry Nodes, materials, lighting, animation, rendering and export. Inspect real scenes and viewport images, refine the result and restore checkpoints. OAuth connects your chat to Blender Bridge Desktop on an online Windows 10/11 x64 computer running Blender 4.2+. The chat can run on another device. Requires an active Blender Bridge account; 7-day trial available. AI model access is separate.
Fast multi-format CAD previews, geometry checks and conversion; measure and share in the workspace.
Convert Revit files to XKT, IFC, or DWG and query BIM data via natural language.
