Pyrestoolbox MCP

🚀 pyResToolbox MCP Server

pyResToolbox MCP Server 是一個生產就緒的服務器，它基於 Model Context Protocol (MCP) 構建，讓像 Claude 這樣的 AI 智能體能夠訪問全面的油藏工程庫 pyResToolbox。現在，Claude 可以通過自然對話執行復雜的 PVT 計算、油井性能分析和油藏模擬任務。

🚀 快速開始

安裝

前提條件：Python 3.10+（推薦使用 UV 包管理器，但非必需）

# 1. 克隆倉庫
git clone https://github.com/gabrielserrao/pyrestoolbox-mcp.git
cd pyrestoolbox-mcp

# 2. 安裝 UV（可選，但比 pip 快 10 - 100 倍）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. 配置和測試
make uv-install    # 創建虛擬環境並安裝依賴項
make uv-test       # 驗證所有 47 個工具是否正常工作

連接到 Claude Desktop

將以下內容添加到你的 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

⚠️ 重要提示

對於 uv 和項目目錄，請使用絕對路徑。像 Claude Desktop 這樣的 GUI 應用程序不會繼承你終端的 PATH 環境變量。

查找你的 UV 路徑：

# macOS/Linux
which uv

# Windows (PowerShell)
Get-Command uv | Select-Object -ExpandProperty Source

配置示例：

{
  "mcpServers": {
    "pyrestoolbox": {
      "command": "/absolute/path/to/uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/pyrestoolbox-mcp",
        "fastmcp",
        "run",
        "server.py"
      ]
    }
  }
}

常見的 UV 路徑：

• macOS/Linux：/Users/username/.local/bin/uv 或 /home/username/.local/bin/uv
• Windows：C:\Users\username\.cargo\bin\uv.exe

示例（macOS）：

{
  "mcpServers": {
    "pyrestoolbox": {
      "command": "/Users/john/.local/bin/uv",
      "args": [
        "run",
        "--directory",
        "/Users/john/projects/pyrestoolbox-mcp",
        "fastmcp",
        "run",
        "server.py"
      ]
    }
  }
}

示例（Linux）：

{
  "mcpServers": {
    "pyrestoolbox": {
      "command": "/home/john/.local/bin/uv",
      "args": [
        "run",
        "--directory",
        "/home/john/projects/pyrestoolbox-mcp",
        "fastmcp",
        "run",
        "server.py"
      ]
    }
  }
}

示例（Windows）：

{
  "mcpServers": {
    "pyrestoolbox": {
      "command": "C:\\Users\\john\\.cargo\\bin\\uv.exe",
      "args": [
        "run",
        "--directory",
        "C:\\Users\\john\\projects\\pyrestoolbox-mcp",
        "fastmcp",
        "run",
        "server.py"
      ]
    }
  }
}

完全重啟 Claude Desktop（退出並重新打開，而不僅僅是關閉窗口），然後你就可以開始使用了！

首次查詢

打開 Claude Desktop 並嘗試輸入：

"What's the bubble point pressure for a 35° API oil at 180°F with 800 scf/stb solution GOR and 0.75 gas gravity?"

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

✨ 主要特性

• 47 個生產就緒的工具：所有工具都經過測試和驗證。
• 行業標準關聯式：包括 Standing、Valko - McCain、Velarde、DAK、Beggs - Robinson、Corey、LET 等。
• 油田單位制：使用常見的油田單位（psia、°F、STB/day、MSCF/day）。
• 數組支持：可同時計算多個壓力下的屬性。
• 零配置：可直接與 Claude Desktop 配合使用。
• GPL - 3.0 許可證：免費且開源。

📦 安裝指南

安裝依賴

# 克隆倉庫
git clone https://github.com/gabrielserrao/pyrestoolbox-mcp.git
cd pyrestoolbox-mcp

# 安裝 UV（可選）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 創建虛擬環境並安裝依賴
make uv-install

# 測試安裝
make uv-test

連接到 Claude Desktop

按照上述“快速開始”部分的說明，將配置信息添加到 Claude Desktop 的配置文件中。

💻 使用示例

基礎用法

import asyncio
from fastmcp.client import InMemoryTransport
from pyrestoolbox_mcp import mcp

async def calculate_pvt():
    transport = InMemoryTransport(mcp)

    async with transport.get_client() as client:
        # 計算泡點壓力
        pb_result = await client.call_tool(
            "oil_bubble_point",
            {
                "api": 35.0,
                "degf": 180.0,
                "rsb": 800.0,
                "sg_g": 0.75,
                "method": "VALMC"
            }
        )
        pb = pb_result['value']
        print(f"Bubble Point: {pb:.2f} psia")

        # 計算多個壓力下的溶解氣油比
        rs_result = await client.call_tool(
            "oil_solution_gor",
            {
                "api": 35.0,
                "degf": 180.0,
                "p": [1000, 2000, 3000, pb, 4000],
                "sg_g": 0.75,
                "pb": pb,
                "rsb": 800.0,
                "method": "VELAR"
            }
        )
        print(f"Rs values: {rs_result['value']}")

        # 訪問配置資源
        methods = await client.read_resource("config://methods")
        print(f"Available methods:\n{methods.content}")

asyncio.run(calculate_pvt())

高級用法

# 啟動 HTTP 服務器
uv run fastmcp run server.py --transport http --port 8000

# 或者使用 Docker
docker-compose --profile http up -d

然後使用任何支持 MCP 協議的 MCP 客戶端或 HTTP 客戶端進行連接。

📚 詳細文檔

可以進行的操作

原油 PVT 分析

• 計算泡點壓力（Standing、Valko - McCain、Velarde 方法）
• 計算溶解氣油比、地層體積係數、粘度、密度、壓縮係數
• 為模擬器生成全面的黑油表

天然氣 PVT 分析

• 計算壓縮因子（DAK、Hall - Yarborough、WYW、Burrows 方法）
• 計算含雜質（CO₂、H₂S、N₂、H₂）的臨界性質
• 計算天然氣粘度、密度、壓縮係數、擬壓力
• 計算地層體積係數

油井性能與流入動態關係（IPR）

• 計算油井和天然氣井的產量（徑向和線性流動）
• 生成垂直井和水平井的 IPR 曲線
• 計算低於泡點壓力下的 Vogel IPR
• 對滲透率、表皮係數、油藏壓力進行敏感性分析

油藏模擬支持

• 生成相對滲透率表（SWOF、SGOF、SGWFN）
• 使用 Corey 和 LET 關聯式
• 計算 Van Everdingen & Hurst 含水層影響函數（AQUTAB）
• 進行 Rachford - Rice 閃蒸計算以分析相態行為

高級計算

• 計算鹽水性質（甲烷和 CO₂ 飽和）
• 進行 CO₂ 封存研究
• 進行油藏非均質性分析（Lorenz 係數、beta 參數）
• 分析層滲透率分佈
• 提供組分庫（100 多種烴類的臨界性質）

配置與幫助

• 查詢可用的計算方法和關聯式
• 訪問單位制文檔
• 獲取物理常數
• 提供全面的使用指南

給 Claude 的示例查詢

基本 PVT 計算

"Calculate Z-factor for gas with SG 0.7 at 3500 psia and 180°F using DAK method"
"What's the oil formation volume factor for 38° API oil at 3000 psia, 175°F with Rs=600?"
"Compare bubble point pressures using Standing, Valko-McCain, and Velarde for 35° API oil"

油井性能分析

"Generate IPR curve for well: 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"
"Calculate oil production rate at 2000 psia flowing pressure for the same well"
"Show me how permeability affects production - test 50, 100, 150, 200, 250 mD"

模擬準備

"Generate a SWOF relative permeability table using Corey correlation with 25 rows,
 kromax=1.0, krwmax=0.25, swc=0.15, sorw=0.15, no=2.5, nw=1.5"
"Create aquifer influence functions for dimensionless radius 10.0"
"Generate black oil table from 500 to 5000 psia for 38° API oil at 175°F"

油藏非均質性

"Convert Lorenz coefficient 0.5 to Dykstra-Parsons beta"
"Generate layered permeability distribution for Lorenz coefficient 0.6,
 10 layers, average permeability 100 mD"

多步驟工作流

"Perform complete reservoir analysis: Calculate bubble point, generate PVT table,
 create IPR curve, and analyze well performance for 38° API oil at 175°F with
 initial pressure 4000 psia"
"Design a well completion: Calculate optimal flowing pressure, generate IPR,
 and compare different skin factors"
"Evaluate a gas reservoir: Calculate critical properties, generate IPR,
 and compare different Z-factor methods"

高級查詢

包括全面的 PVT 工作流、天然氣分析、油井性能與 IPR、敏感性分析、鹽水與 CO₂ 封存、油藏非均質性、相態行為與閃蒸計算、組分庫、經濟與優化、比較與基準測試、教育查詢、故障排除與驗證等方面的查詢示例。

查詢提示

💡 使用建議

1. 具體明確：包含所有相關參數（API、溫度、壓力等）。
2. 指定方法：提及你想要使用的關聯式（VALMC、DAK、Corey、LET 等）。
3. 包含單位：始終指定單位（psia、degF、mD、ft 等）。
4. 請求比較：要求比較不同方法或場景。
5. 請求表格：當需要多個值時，請求以表格形式呈現結果。
6. 跟進問題：基於之前的答案進行復雜工作流的查詢。

單位系統

所有計算均遵循行業標準，使用 油田單位制（美國油田）：

屬性	單位	示例
壓力	psia	3000 psia
溫度	°F	180°F
滲透率	mD	100 mD
油層厚度	ft	50 ft
粘度	cP	0.85 cP
油產量	STB/day	542 STB/day
氣產量	MSCF/day	1250 MSCF/day
原油相對密度	API° 或 SG	35° API
天然氣相對密度	SG（空氣 = 1）	0.75
溶解氣油比	scf/stb	800 scf/stb
原油地層體積係數	rb/stb	1.25 rb/stb
天然氣地層體積係數	rcf/scf	0.0045 rcf/scf
壓縮係數	1/psi	1.2×10⁻⁵ 1/psi
密度	lb/ft³	42.5 lb/ft³

你可以隨時向 Claude 詢問："What units does pyRestToolbox use?" 以訪問完整的單位文檔。

項目架構

項目結構

pyrestoolbox-mcp/
├── src/pyrestoolbox_mcp/
│   ├── server.py              # 主 MCP 服務器 (FastMCP)
│   ├── config.py              # 服務器配置與常量
│   ├── tools/                 # 47 個 MCP 工具實現 (約 13,800 行代碼)
│   │   ├── oil_tools.py       # 17 個原油 PVT 工具
│   │   ├── gas_tools.py       # 11 個天然氣 PVT 工具
│   │   ├── inflow_tools.py    # 4 個油井性能工具
│   │   ├── simtools_tools.py  # 3 個模擬支持工具
│   │   ├── brine_tools.py     # 2 個鹽水性質工具
│   │   ├── layer_tools.py     # 5 個非均質性工具
│   │   └── library_tools.py   # 1 個組分庫工具
│   ├── models/                # Pydantic 驗證模型
│   │   ├── oil_models.py
│   │   ├── gas_models.py
│   │   ├── inflow_models.py
│   │   ├── simtools_models.py
│   │   ├── brine_models.py
│   │   ├── layer_models.py
│   │   └── library_models.py
│   └── resources/             # MCP 配置資源
│       └── config_resources.py
├── tests/                     # 測試套件 (pytest + 自定義)
│   ├── test_oil_tools.py
│   ├── test_gas_tools.py
│   └── conftest.py
├── examples/                  # 10 個全面的工作流示例
│   ├── basic_usage.py
│   ├── pvt_workflow.py
│   ├── gas_well_analysis.py
│   └── ...
├── server.py                  # 入口點
├── pyproject.toml            # UV/pip 配置
├── Makefile                  # 開發命令
├── Dockerfile                # Docker 部署
└── docker-compose.yml        # 多傳輸方式部署

工作原理

1. FastMCP 服務器：處理 MCP 協議通信（STDIO、HTTP、SSE）。
2. Pydantic 模型：驗證所有輸入並提供描述性錯誤信息。
3. 工具層：47 個函數封裝了 pyrestoolbox 的計算功能。
4. pyRestToolbox：執行實際的油藏工程計算。
5. 類型轉換：處理 numpy/pandas/mpmath 數據的 JSON 序列化。

工具分類

類別	數量	描述
原油 PVT	17	泡點壓力、溶解氣油比、地層體積係數、粘度、密度、壓縮係數、黑油表
天然氣 PVT	11	壓縮因子、臨界性質、天然氣地層體積係數、粘度、密度、擬壓力
流入動態	4	徑向和線性流動的油/氣產量、IPR 曲線生成
模擬	3	相對滲透率、含水層函數、Rachford - Rice 閃蒸計算
鹽水	2	甲烷和 CO₂ 飽和鹽水性質
非均質性	5	Lorenz 係數、beta 轉換、層滲透率分佈
組分庫	1	100 多種組分的臨界性質
配置	4	單位制、方法、常量、幫助資源

🔧 技術細節

可用的計算方法

原油關聯式

• 泡點壓力
  • VALMC - Valko & McCain (2003) - 推薦用於大多數應用場景
  • STAN - Standing (1947) - 經典關聯式
  • VELAR - Velarde (1997) - 適用於特定地區
• 溶解氣油比（Rs）
  • VELAR - Velarde (1997)
  • STAN - Standing (1947)
  • VALMC - Valko & McCain (2003)
• 地層體積係數（Bo）
  • MCAIN - McCain et al. (1988) - 推薦使用
  • STAN - Standing (1947)
• 粘度
  • BR - Beggs & Robinson (1975)

天然氣關聯式

• 壓縮因子（Z - factor）
  • DAK - Dranchuk & Abou - Kassem (1975) - 推薦用於烴類氣體
  • HY - Hall & Yarborough (1973) - 快速，適用於大多數情況
  • WYW - Wang, Ye & Wu (2021) - 速度適中
  • BUR - Burgoyne, Nielsen & Stanko (2025) - 通用的基於 EOS 的關聯式，最適用於高非烴含量（CO₂、H₂S、N₂、H₂）的氣體，包括 100% CO₂，是唯一支持 H₂ 的方法 (SPE - 229932 - MS)
• 臨界性質
  • PMC - Piper, McCain & Corredor (1993) - 推薦用於烴類氣體
  • SUT - Sutton (1985)
  • BUR - Burgoyne, Nielsen & Stanko (2025) - 通用關聯式，最適用於高非烴含量的氣體 (SPE - 229932 - MS)
• 粘度
  • LGE - Lee, Gonzalez & Eakin (1966)

相對滲透率

• 曲線類型
  • COR - Corey (1954) - 冪律，簡單
  • LET - Lomeland, Ebeltoft & Thomas (2005) - 靈活，可生成複雜形狀
• 表格類型
  • SWOF - 油水飽和度函數
  • SGOF - 油氣飽和度函數
  • SGWFN - 氣水飽和度函數（三相）

📄 許可證

GNU 通用公共許可證 v3.0 (GPL - 3.0)

此 MCP 服務器基於 pyResToolbox 構建，該庫採用 GPL - 3.0 許可證。本項目完全遵守 GPL - 3.0 許可證條款。

關鍵點：

• 免費開源軟件。
• 你可以在 GPL - 3.0 條款下使用、修改和分發。
• 任何修改也必須在 GPL - 3.0 許可證下發布。
• 不提供任何保證（詳情請參閱 LICENSE 文件）。
• 允許商業使用，但需遵守 GPL - 3.0 條款。

請參閱 LICENSE 文件以獲取完整的許可證文本。

項目狀態

方面	狀態	詳情
測試		100% 工具覆蓋率
生產	✅ 就緒	所有工具已驗證
文檔	✅ 完整	README、示例、指南
許可證	GPL - 3.0	與上游一致
Python	3.10+	全程使用類型提示
框架	FastMCP 2.0+	現代 MCP 實現

請參閱 PRODUCTION_READY.md 文件以獲取詳細的驗證結果。

版本歷史

v1.0.0 (2024 - 11 - 15) - 初始生產版本

• 47 個生產就緒的工具。
• 100% 測試覆蓋率。
• 支持 Docker 部署。
• 全面的文檔。
• 符合 GPL - 3.0 許可證。

請參閱 CHANGELOG.md 文件以獲取詳細的版本歷史。

路線圖

計劃功能

• [ ] 帶有交互式表單的 HTTP 傳輸 Web UI。
• [ ] 常見任務的額外工作流示例。
• [ ] 性能基準測試套件。
• [ ] 擴展的模擬工具（網格處理、ECLIPSE 實用工具）。
• [ ] 集成 Jupyter 筆記本並提供示例。
• [ ] API 文檔網站（Sphinx/MkDocs）。
• [ ] HTTP 部署的速率限制和身份驗證。
• [ ] Prometheus 指標導出。

請參閱 open issues 以獲取完整的提議功能和已知問題列表。

上游集成

我們正在探索將改進貢獻回 pyResToolbox 的機會，包括：

• 獨立的 gas_grad2sg 實現（修復 bug）。
• 增強的類型提示。
• 額外的驗證實用工具。

相關項目

核心依賴

• pyResToolbox - Mark Burgoyne 開發的油藏工程庫。
• FastMCP - 用於 MCP 服務器的 Python 框架。
• Model Context Protocol - Anthropic 制定的 MCP 規範。

類似的 MCP 服務器

• mcp - servers - 官方 MCP 服務器示例。
• awesome - mcp - servers - 精選的 MCP 服務器列表。

石油工程工具

• PVTpy - Python 實現的 PVT 計算工具。
• petbox - 石油工程工具箱。

致謝

本項目的實現離不開以下人員和組織的貢獻：

• Mark Burgoyne - pyResToolbox 的創建者，本 MCP 服務器的基礎。
• Marvin AI Team - FastMCP 框架的開發者。
• Anthropic - 提供 Claude 和 Model Context Protocol 規範。
• 油藏工程社區 - 開發和完善了本項目中實現的關聯式。

特別感謝所有幫助改進本項目的貢獻者！

引用

如果你在學術或商業工作中使用此 MCP 服務器，請引用原始的 pyResToolbox 庫：

@software{pyrestoolbox,
  author = {Burgoyne, Mark W.},
  title = {pyResToolbox: A Collection of Reservoir Engineering Utilities},
  url = {https://github.com/mwburgoyne/pyResToolbox},
  version = {2.x},
  year = {2024}
}

對於此 MCP 服務器：

@software{pyrestoolbox_mcp,
  author = {Serrao, Gabriel},
  title = {pyResToolbox MCP Server: AI-Powered Reservoir Engineering Calculations},
  url = {https://github.com/gabrielserrao/pyrestoolbox-mcp},
  version = {1.0.0},
  year = {2024},
  note = {Built on pyResToolbox by Mark W. Burgoyne}
}

支持

獲取幫助

• MCP 服務器問題：
  • 查看 Troubleshooting 部分。
  • 查看 examples/ 目錄。
  • 搜索 現有問題。
  • 打開一個 新問題。
• 計算準確性或 pyResToolbox 功能問題：
  • 查看 pyResToolbox 文檔。
  • 查看 pyResToolbox 問題。
• FastMCP 框架問題：
  • 查看 FastMCP 文檔。
• Model Context Protocol 問題：
  • 查看 MCP 規範。
  • 加入 MCP Discord（如果可用）。

社區

• 討論：GitHub Discussions
• 問題：GitHub Issues
• 拉取請求：Contributing Guide

⭐ 給項目加星

如果你覺得這個項目有用，請在 GitHub 上給它加星！星星可以幫助其他人發現這個項目，並激勵持續開發。

☕ 請我喝咖啡

支持本項目的開發和維護： 點擊支持

你的支持有助於讓這個項目為石油工程社區保持免費和開源！

📈 加星曆史

---

為石油工程社區用心打造

由 Gabriel Serrao 創建

報告 Bug · 請求功能 · 文檔 · 示例