Metadata-Version: 2.4
Name: petroleum-mcp
Version: 0.4.0
Summary: Local-first MCP server for petroleum data. Reads LAS well logs; DLIS, SEG-Y, and pump cards next.
Project-URL: Homepage, https://github.com/ameyxd/petromcp
Project-URL: Repository, https://github.com/ameyxd/petromcp
Project-URL: Issues, https://github.com/ameyxd/petromcp/issues
Project-URL: Changelog, https://github.com/ameyxd/petromcp/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/ameyxd/petromcp/blob/main/docs/TOOLS_REFERENCE.md
Author: Amey Ambade
License: MIT
License-File: LICENSE
Keywords: claude,las,lasio,mcp,model-context-protocol,oil-and-gas,petroleum,petrophysics,subsurface,well-log
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: fastmcp<3,>=2.0
Requires-Dist: lasio<0.32,>=0.31
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic<3,>=2.6
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# petromcp

An MCP server that lets Claude read your LAS well log files directly.
Local-first. Synthetic data only by default. DLIS, SEG-Y, and pump card
support coming next.

## What this gives you

LLM hosts cannot read binary or semi-structured petroleum formats. petromcp
wraps the established open-source parsers — `lasio` today, with `dlisio`
and `segyio` queued for the next slices — and exposes them as MCP tools, so
you can have a conversation with your data instead of copy-pasting curve
values into chat.

## Privacy first

petromcp runs on your machine. It refuses to read any file outside an
explicit allowlist. There is no telemetry, no phone-home, no automatic
updates. Read [docs/DATA_PRIVACY.md](docs/DATA_PRIVACY.md) before pointing
it at real data.

## Install

Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).

Add petromcp to your MCP host's config — no clone, no build:

```json
{
  "mcpServers": {
    "petromcp": {
      "command": "uvx",
      "args": ["petroleum-mcp", "serve"]
    }
  }
}
```

On macOS that file is
`~/Library/Application Support/Claude/claude_desktop_config.json`. Restart
the host afterwards. macOS notes and troubleshooting:
[docs/INSTALL.md](docs/INSTALL.md).

To work on petromcp rather than just use it:

    git clone https://github.com/ameyxd/petromcp
    cd petromcp
    make setup
    make install-claude

## Configure

By default petromcp can read nothing. Tell it which directories are fair
game:

    uvx petroleum-mcp config init
    uvx petroleum-mcp config add-path ~/petroleum/wells

Or, if you want to try it without your own data, generate the synthetic
sample from a checkout and allowlist that:

    make generate
    uv run --no-sync petromcp config add-path "$(pwd)/examples/sample_data"

Restart your MCP host after editing the allowlist — it is read once at
startup.

## Use

Open a new conversation and ask, in plain language:

    What's wrong with this well log? /path/to/well.las
    Compare these two wells: /path/to/A.las and /path/to/B.las
    Convert 1500 psi to kPa.

Claude picks the right tool, reads the file through petromcp, and answers.

## Tools

| Tool                    | What it does                                          |
|-------------------------|-------------------------------------------------------|
| `read_las_file`         | Header-level summary of a LAS file                    |
| `summarize_las_curves`  | Per-curve min, max, mean, stddev, gap percentage      |
| `read_las_curve`        | Depths and values for one curve, with sampling cap    |
| `compare_well_logs`     | Common curves, depth overlap, unit consistency, flags |
| `convert_units`         | ft<->m, psi<->kPa, psi<->bar, bbl<->m3, degF<->degC, mD<->m2 |
| `qc_a_well_log` prompt  | Walks Claude through a standard QC pass               |

Every tool is read-only and opens no network connection, and declares that
in its MCP annotations. Full reference:
[docs/TOOLS_REFERENCE.md](docs/TOOLS_REFERENCE.md).

DLIS, SEG-Y, and pump card support land in subsequent releases.

## Status

v0.4 ships the LAS slice, a comparison tool, a units utility, and
config-management CLI subcommands. The remaining formats are tracked in
[SPEC_petromcp.md](SPEC_petromcp.md). The non-goals list there is real;
read it before filing feature requests.

Release history: [CHANGELOG.md](CHANGELOG.md). Security policy and threat
model: [SECURITY.md](SECURITY.md).

## License

MIT.
