awesome_well_mcp

What is awesome_well_mcp?

awesome_well_mcp is a borehole structure diagram generation tool built on the Model Context Protocol (MCP). It automatically generates borehole structure diagrams and information charts from well data, and is technically supported by the He Shiming and Tang Ming research group at the Drilling Research Institute of Southwest Petroleum University.

How to use awesome_well_mcp?

You can install via PyPI using uvx awesome_well_mcp, or by cloning the source repository and running uv run main.py. Configure an MCP client (e.g., Cherry Studio) with a stdio server pointing to the installed command. The tool exposes one MCP tool named generate_well_structure which accepts a well_data dictionary as its only parameter.

Key features of awesome_well_mcp

• Supports four basic well types: straight, deviated, horizontal, and vertical-to-horizontal
• Automatically generates borehole structure PNG images and information charts
• Produces CSV data files for stratigraphy, casing, hole sections, and more
• Automatic file archiving with timestamp folders
• Token‑optimized image paths (<1200 tokens) to reduce API costs
• Configurable legend display and pilot‑hole guide line for side‑tracking wells

Use cases of awesome_well_mcp

• Quickly generate borehole structure diagrams for straight, deviated, horizontal, and vertical‑to‑horizontal wells
• Visualise well casing, hole sections, and stratigraphy along with pressure data
• Automatically produce structured reports and CSV datasets for drilling engineering analysis
• Design side‑tracking wells by configuring pilot‑hole guide lines
• Archive multiple well designs with timestamp‑stamped folders for easy retrieval

FAQ from awesome_well_mcp

What well types does awesome_well_mcp support?

It supports four basic types: straight well, deviated well, horizontal well, and vertical‑to‑horizontal well. Side‑tracking (branch) wells can be represented by enabling the pilotHoleGuideLine with "side_tracking": true.

How do I install awesome_well_mcp?

The recommended method is via PyPI using uvx awesome_well_mcp. Alternatively, you can clone the source repository and run uv run main.py. Both methods require Python 3.8 or later and the uv package manager.

What files does awesome_well_mcp generate per request?

It generates a PNG borehole structure diagram (well_structure_plot.png), a PNG information chart (well_info.png), a Markdown report (well_structure_report.md), and several CSV files (e.g., stratigraphy.csv, casing_sections.csv, hole_sections.csv, drilling_fluid_pressure.csv, deviationData.csv, location.csv) along with their raw data versions. All files are archived in a timestamp folder.

How do I configure pilot‑hole guide lines for side‑tracking wells?

Include a pilotHoleGuideLine object in your wellboreStructure data with fields topDepth_m, bottomDepth_m, diameter_mm, display, highlight, and side_tracking: true. This is available for horizontal well or deviated well types.

What are the data structure requirements for stratigraphy and wellbore sections?

Stratigraphy must be ordered from shallow to deep with consecutive depths. Hole sections and casing sections must also follow depth order; casing outer diameter typically decreases downwards. The last hole section’s bottom depth must equal totalDepth_m. Pressure segments must have contiguous depth intervals and a pressure window minimum greater than pore pressure.