pyrestoolbox-mcp: 산업 표준 석유 공학 계산을 통한 AI 어시스턴트 강화

산업 표준 석유 공학 계산으로 AI 어시스턴트의 능력을 강화하세요

빠른 시작 (Quick Start) • 기능 (Features) • 예시 (Examples) • 문서 (Documentation) • 기여하기 (Contributing)

PVT 분석 (PVT Analysis) • 유정 성능 (Well Performance) • 노달 분석 (Nodal Analysis) • DCA • 물질 수지 (Material Balance) • 시뮬레이션 지원 (Simulation Support) • 염수 특성 (Brine Properties) • 지질역학 (Geomechanics) • 불균질성 분석 (Heterogeneity Analysis)

Claude와 같은 AI 에이전트가 종합적인 저류층 공학 라이브러리인 pyResToolbox에 접근할 수 있도록 하는 프로덕션 준비 완료된 Model Context Protocol (MCP) 서버입니다. 이제 Claude는 자연스러운 대화를 통해 정교한 PVT 계산, 유정 성능 분석 및 저류층 시뮬레이션 작업을 수행할 수 있습니다.

이 프로젝트가 유용하다고 생각되신다면, 저에게 커피 한 잔을 사주시는 것을 고려해 주세요! 여러분의 지원은 이 오픈 소스 도구를 유지하고 개선하는 데 도움이 됩니다.

이 MCP 서버는 AI 어시스턴트와 석유 공학 워크플로우 사이의 간극을 메워줍니다. 저류층 특성을 수동으로 계산하거나 복잡한 스크립트를 작성하는 대신, 단순히 Claude에게 다음과 같이 요청할 수 있습니다:

"Valko-McCain 상관식을 사용하여 용해 GOR이 800 scf/stb이고 가스 비중이 0.75인 180°F에서 API 35° 오일의 버블 포인트 압력(bubble point pressure)을 계산해줘"

"Pi=4000 psia, Pb=3500 psia, API 38°, 175°F, 지층 두께(pay thickness) 75 ft, 투과율(permeability) 150 mD인 내 유정에 대한 IPR 곡선을 생성해줘"

"500에서 5000 psia 사이의 압력을 가진 시뮬레이션용 블랙 오일 테이블(black oil table)을 만들어줘"

Claude는 산업 표준 상관식을 사용하여 계산을 실행하고 정확하고 형식이 지정된 결과를 반환합니다.

pyResToolbox Mark Burgoyne 제작 - 저류층 공학 계산을 위한 종합 Python 라이브러리
FastMCP - MCP 서버 구축을 위한 현대적인 Python 프레임워크
Model Context Protocol Anthropic 제작 - AI 애플리케이션 통합을 위한 표준

108개의 프로덕션 준비 완료된 도구 (Production-Ready Tools)

• 모든 도구는 테스트 및 검증됨
  산업 표준 상관관계 (Industry-Standard Correlations)
• Standing, Valko-McCain, Velarde, DAK, Beggs-Robinson, Corey, LET 등
  이중 단위 지원 (Dual Unit Support)
• 현장 단위 (psia, °F, ft) 및 미터법 단위 (barsa, °C, m)
  배열 지원 (Array Support)
• 여러 압력에서 동시에 물성 계산 가능
  제로 설정 (Zero Configuration)
• Claude Desktop에서 즉시 사용 가능
  GPL-3.0 라이선스 (GPL-3.0 Licensed)
• 무료 및 오픈 소스

사전 요구 사항 (Prerequisites): Python 3.10+ (UV 패키지 매니저 권장하지만 선택 사항)

# 1. 저장소 복제 (Clone the repository)
git clone https://github.com/gabrielserrao/pyrestoolbox-mcp.git
cd pyrestoolbox-mcp
...

이 내용을 Claude Desktop 설정 파일에 추가하세요:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

중요 (IMPORTANT): uv와 프로젝트 디렉토리 모두에 절대 경로를 사용하세요. Claude Desktop과 같은 GUI 애플리케이션은 터미널의 PATH를 상속받지 않습니다.

UV 경로 찾기:

# macOS/Linux
which uv
# Windows (PowerShell)
...

설정 (Configuration):

{
"mcpServers": {
"pyrestoolbox": {
...

일반적인 UV 경로:

macOS/Linux: /Users/username/.local/bin/uv 또는 /home/username/.local/bin/uv

Windows: C:\Users\username\.cargo\bin\uv.exe

예시 (macOS):

{
"mcpServers": {
"pyrestoolbox": {
...

예시 (Linux):

{
"mcpServers": {
"pyrestoolbox": {
...

예시 (Windows):

{
"mcpServers": {
"pyrestoolbox": {
...

Claude Desktop을 완전히 재시작하세요 (단순히 창을 닫는 것이 아니라 종료 후 다시 열기). 이제 준비되었습니다!

이 저장소의 SKILL/ 폴더에는 AI 어시스턴트에게 108개의 모든 도구를 사용하는 정확한 방법(올바른 매개변수 이름, 유효한 메서드 코드, 검증 제약 조건 및 다단계 워크플로)을 가르치는 사전 구축된 스킬이 포함되어 있습니다.

포함된 내용:

파일	용도
SKILL/pyrestoolbox-mcp.skill	즉시 설치 가능한 스킬 번들 (zip 형식)
SKILL/SKILL.md	YAML 프론트매터 (front-matter) 트리거 조건이 포함된 스킬 정의
SKILL/tools-reference.md	108개 모든 도구에 대한 완전한 파라미터 (parameter) 참조

설치 방법 (Claude Code):

스킬 파일을 Claude 스킬 디렉토리로 복사하세요:

cp SKILL/SKILL.md ~/.claude/skills/pyrestoolbox-mcp.md
# 선택 사항이지만 권장됨 — 전체 파라미터 참조
mkdir -p ~/.claude/skills/references
...

설치가 완료되면, 저류층 공학 (reservoir engineering) 계산, PVT 분석, 유정 성능 (well performance), 지질역학 (geomechanics) 또는 pyResToolbox 관련 주제에 대해 질문할 때 스킬이 자동으로 활성화됩니다.

이 스킬이 AI에게 가르치는 내용:

• 정확한 파라미터 (parameter) 이름 (pwf가 아닌 psd, 가스 도구의 경우 sg_g가 아닌 sg, method 대신 zmethod 등)
• 모든 유효한 열거형 (enum) 문자열 ("VALMC", "DAK", "SWOF", "COR" 등)
• 모든 도구에 대한 필수 파라미터와 선택적 파라미터 구분
• 수치 검증 제약 조건 (API 0–100, 가스 비중 (SG) 0.5–2.0, 포아송 비 (Poisson's ratio) 0–0.5)
• 일반적인 다단계 워크플로 (PVT 분석, 유정 성능, 시뮬레이션 입력, 지질역학 시추 창 (drilling window))

Claude Desktop을 열고 다음과 같이 시도해 보세요:

"35° API 오일, 180°F 온도, 800 scf/stb 용존 GOR, 0.75 가스 비중 (gas gravity) 조건에서 버블 포인트 압력 (bubble point pressure)은 얼마인가요?"

Claude는 oil_bubble_point 도구를 사용하여 다음과 같은 결과를 반환합니다:

Bubble Point Pressure: 3,456.7 psia
Method: Valko-McCain (VALMC)
Inputs: API=35°, T=180°F, Rs=800 scf/stb, SG_gas=0.75

• 버블 포인트 압력 계산 (Standing, Valko-McCain, Velarde)

• 용존 GOR (solution GOR), 형성 부피 계수 (formation volume factor), 점도 (viscosity), 밀도 (density), 압축성 (compressibility)

• 시뮬레이터를 위한 종합적인 블랙 오일 테이블 (black oil tables) 생성

• Z-factor 계산 (DAK, Hall-Yarborough, WYW, BUR/Peng-Robinson EOS)

• BUR 방법을 통한 수소 대응 가능 (Hydrogen-capable) 가스 PVT (SPE-229932-MS) - 순수 CO₂ 및 30% 이상의 H₂를 포함한 임의의 혼합물 처리

• 불순물(CO₂, H₂S, N₂, H₂)이 포함된 임계 특성 (Critical properties)

• 가스 점도 (viscosity), 밀도 (density), 압축성 (compressibility), 의사압력 (pseudopressure)

• 형성 부피 계수 (Formation volume factors), 하이드레이트 예측 (hydrate prediction), 수분 함량 (water content)

• 오일 및 가스 생산율 (radial 및 linear flow)

• 수직 및 수평정 (vertical and horizontal wells)을 위한 IPR 곡선 생성

• 버블 포인트 (bubble point) 미만 압력을 위한 Vogel IPR

• 투과율 (permeability), 스킨 (skin), 저류층 압력 (reservoir pressure)에 대한 민감도 분석 (Sensitivity analysis)

• 상대 투과율 (Relative permeability) 테이블 (SWOF, SGOF, SGWFN) 및 Corey, LET, Jerauld 곡선군

• 상대 투과율 피팅 (Rel perm fitting) - 실험 데이터를 모든 모델군에 피팅하거나 최적의 피팅 모델 자동 선택

• LET 물리적 타당성 검사 (physical feasibility checking)

• PVDO/PVDG/PVTO 블랙 오일 테이블 및 PVTW 물 PVT 생성

• ECLIPSE를 위한 VFPPROD/VFPINJ 리프트 곡선 (lift curve) 테이블

• Van Everdingen & Hurst 대수층 영향 함수 (AQUTAB)

• 상 거동 (phase behavior)을 위한 Rachford-Rice 플래시 계산 (flash calculations)

• 네 가지 다상 VLP 상관관계 (correlations):
  Woldesemayat-Ghajar (WG), Hagedorn-Brown (HB), Gray, Beggs & Brill (BB)

• 다중 세그먼트 경사정 및 수평 완결 (단순 수직 파이프가 아닌 형태)

• IPR 곡선 생성 (가스, 오일, 물정)

• VLP 유출 곡선 (outflow curves) 및 운전점 (operating point) 계산

• 생산 및 주입 모드 지원

• ECLIPSE/Intersect 시뮬레이터를 위한 VFPPROD/VFPINJ 테이블 생성

• 일관된 유체 특성화를 위한 GasPVT 및 OilPVT 래퍼 클래스 (wrapper classes)

• Arps 감퇴 (exponential, hyperbolic, harmonic)

• 생산율 (Rate) 및 누적 생산량 (cumulative production) 예측

• EUR 추정

• Duong 타이트/비전통적 (tight/unconventional) 감퇴

• 생산 비율 분석 (WOR, GOR, WGR)

• OGIP 추정을 위한 P/Z 가스 물질 수지 (material balance)

• OOIP 추정을 위한 Havlena-Odeh 오일 물질 수지

• Cole plot 진단 및 회귀 분석 (regression)

• 수직/수평 응력 (Vertical/horizontal stress), 공극압 예측 (pore pressure prediction, Eaton)

• 파쇄 구배 (Fracture gradient), 파쇄 압력 (breakdown pressure), 이수 밀도 창 (mud weight window)

• 시추공 파쇄 (Borehole breakout), 모래 생산 (sand production), 단층 안정성 (fault stability)

• 탄성 계수 (Elastic moduli), 암석 강도 (rock strength), 압밀 (compaction), 열 응력 (thermal stress)

• 로그 기반 UCS (UCS from logs), 응력 다각형 (stress polygon), 임계 압력 강하 (critical drawdown)

• CH₄ 포화 염수 특성 (density, viscosity, FVF, compressibility)

• 격리 연구를 위한 CO₂-염수 상호 용해도 (CO₂-brine mutual solubility)

• Sechenov 염석 효과 (salting-out) 보정을 포함한 다성분 가스 염수 시스템 (CO₂, H₂S, N₂, H₂)용 Soreide-Whitson VLE

• IAPWS-IF97 담수 밀도, Spivey/McCain 염도 보정

• 단일 프레임워크를 통한 성분별 용해도, 함수율 및 열역학적 특성

• 저류층 불균질성 분석 (Lorenz coefficient, beta parameter)

• 층별 투과율 분포 (Layer permeability distributions)

• 성분 라이브러리 (100개 이상의 탄화수소에 대한 임계 특성)

• 민감도 분석 (parameter sweeps, tornado plots)

• 방법론 추천 엔진 (Method recommendation engine)

• 사용 가능한 계산 방법 및 상관관계 (correlations) 조회

• 단위계 문서 접근

• 물리 상수 획득

• 종합 사용 가이드

"DAK 방법을 사용하여 3500 psia, 180°F에서 SG 0.7인 가스의 Z-factor를 계산해줘"
"Rs=600, 3000 psia, 175°F 조건에서 38° API 오일의 오일 형성 함수율 (oil formation volume factor)은 뭐야?"
"35° API 오일에 대해 Standing, Valko-McCain, Velarde를 사용하여 버블 포인트 압력을 비교해줘"

"다음 조건의 유정 IPR 곡선을 생성해줘: Pi=4000 psia, Pb=3500 psia, API 38, T=175°F, h=75 ft, k=150 mD, skin=-2, re=1500 ft, rw=0.5 ft"
"동일한 유정에 대해 유동 압력 2000 psia에서의 오일 생산율을 계산해줘"
...

"Corey 상관관계를 사용하여 25개 행을 가진 SWOF 상대 투과율 테이블을 생성해줘: kromax=1.0, krwmax=0.25, swc=0.15, sorw=0.15, no=2.5, nw=1.5"
"무차원 반경 10.0에 대한 대수층 영향 함수 (aquifer influence functions)를 생성해줘"
...

"Lorenz 계수 0.5를 Dykstra-Parsons beta로 변환해줘"
"Lorenz 계수 0.6, 10개 층, 평균 투과율 100 mD에 대한 층별 투과율 분포를 생성해줘"

"완전한 저류층 분석을 수행해줘: 초기 압력 4000 psia, 175°F 조건의 38° API 오일에 대해 버블 포인트 (bubble point)를 계산하고, PVT 테이블을 생성하며, IPR 곡선을 만들고, 유정 성능 (well performance)을 분석해줘"
...

"가스 비중 (gas gravity) 0.68, 용해 가스-오일비 (solution GOR) 750 scf/stb인 175°F, API 38 오일에 대한 완전한 PVT 테이블을 생성해줘. 500에서 4000 psia 사이의 압력을 포함하고 Rs, Bo, 점도 (viscosity), 밀도 (density)를 보여줘"
...

"2% CO2, 1% H2S, 3% N2를 포함하는 비중 (specific gravity) 0.7 가스의 임계 물성 (critical properties, Tc 및 Pc)을 계산해줘"
"3500 psia, 180°F 가스에 대해 DAK, HY, WYW 방법을 사용하여 Z-factor를 비교해줘"
...

"저류층 압력 4000 psia, 버블 포인트 (bubble point) 3500 psia, 175°F, API 38 오일인 유정의 IPR 곡선을 생성해줘. 유정은 순 페이 두께 (net pay) 75 ft, 투과율 (permeability) 150 mD, 스킨 (skin) -2, 배수 반경 (drainage radius) 1500 ft를 가짐"
...

"투과율 (permeability)에 따라 오일 유량이 어떻게 변하는가? 50에서 250 mD까지의 값을 테스트해줘"
"스킨 계수 (skin factor)가 생산에 미치는 영향은 무엇인가? 스킨 값이 -5에서 +10까지일 때의 유량을 비교해줘"
...

"3000 psia, 175°F 조건의 담수 (fresh water)에 대한 염수 (brine) 물성을 계산해줘"
"저류층 조건(3000 psia, 175°F)에서 염수 (saline brine, 5% NaCl)의 물성은 무엇인가?"
...

"Lorenz 계수 0.5를 Dykstra-Parsons beta 파라미터로 변환해줘"
"생산 로깅 데이터로부터 Lorenz 계수를 계산해줘: 유량 분율 (flow fractions) [0.45, 0.25, 0.15, 0.10, 0.05] 및 투과율 분율 (permeability fractions) [0.30, 0.25, 0.20, 0.15, 0.10]"
...

"조성 [0.5, 0.3, 0.2] 및 K-값 (K-values) [2.5, 1.8, 0.6]를 가진 혼합물에 대해 Rachford-Rice 플래시 (flash) 계산을 수행해줘"
"3성분계 (three-component system)에 대한 기액 평형 (vapor-liquid equilibrium)을 계산해줘"

"메테인 (methane)의 임계 물성 (critical properties)은 무엇인가?"
"에테인 (ethane), 프로판 (propane), 부탄 (butane)의 임계 온도와 압력을 구해줘"
"n-헵테인 (n-heptane)의 분자량 (molecular weight)은 무엇인가?"

"생산을 극대화하기 위한 최적 유동 압력 (optimal flowing pressure)은 무엇인가? IPR을 생성하고 최적 지점 (sweet spot)을 찾아줘"
"자극된 (stimulated, skin -2) 유정과 손상된 (damaged, skin +5) 유정의 생산 유량을 비교해줘"
...
"

"동일한 오일에 대한 Standing vs Valko-McCain vs Velarde 버블 포인트 (bubble point) 상관관계 비교해줘"
"DAK vs HY vs WYW Z-factor 계산법과 이것이 가스 유량 (gas rate) 계산에 미치는 영향 비교해줘"
"동일한 저류층 특성에 대한 방사형 (radial) vs 선형 (linear) 유동 기하학 비교해줘"

"버블 포인트 압력 (bubble point pressure)의 의미를 설명하고 API 35 오일에 대해 계산해줘"
"용해 가스-오일비 (solution GOR)와 생산 가스-오일비 (producing GOR)의 차이점은 무엇인가요? 둘 다 계산해줘"
"가스 비중 (gas gravity)이 Z-factor에 어떤 영향을 미치나요? 다양한 비중에 대한 계산 과정을 보여줘"
...

"내 PVT 데이터를 검증해줘: 버블 포인트 3500 psia, API 38, 175°F, GOR 750 scf/stb - 이 데이터가 타당한가요?"
"내 가스 조성 (gas composition)이 현실적인지 확인해줘: SG 0.7, CO2 5%, H2S 3%, N2 2%"
...

**구체적으로 질문하세요**- 모든 관련 매개변수(API, 온도, 압력 등)를 포함하세요
**방법을 명시하세요**- 원하는 상관관계(VALMC, DAK, Corey, LET 등)를 언급하세요
**단위를 포함하세요**- 항상 단위(psia, degF, mD, ft 등)를 명시하세요
**비교를 요청하세요**- 방법론이나 시나리오 간의 비교를 요청하세요
**표를 요청하세요**- 여러 값이 필요한 경우 표 형식의 결과를 요청하세요
**후속 질문을 하세요**- 복잡한 워크플로우를 위해 이전 답변을 바탕으로 질문을 이어가세요

모든 계산은 산업 표준에 따라 **필드 단위 (Field Units, US Oilfield)**를 기본값으로 사용합니다. `metric: true`로 설정하세요.