Pyrestoolbox MCP

🚀 pyResToolbox MCP Server

このサーバーは、AIエージェント（Claudeなど）に、包括的な油層工学ライブラリである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を開き、以下を試してみましょう:

"35° APIの原油について、180°F、溶解ガス油比800 scf/stb、ガス比重0.75の条件でのバブルポイント圧力はいくらですか？"

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ライセンス - 無料でオープンソースです。

📦 インストール

インストール手順

前提条件: 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のツールがすべて正常に動作することを確認します

💻 使用例

基本的な使用法

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分析

• Z係数の計算 (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係数、ベータパラメータ）
• 層浸透率分布
• 成分ライブラリ（100以上の炭化水素の臨界物性）

設定とヘルプ

• 利用可能な計算方法と相関式のクエリ
• 単位系ドキュメントへのアクセス
• 物理定数の取得
• 包括的な使用ガイド

Claudeへのクエリ例

基本的なPVT計算

"3500 psia、180°Fで、比重0.7のガスのZ係数をDAK法で計算してください。"
"38° APIの原油について、3000 psia、175°F、溶解ガス油比600の条件での体積係数を計算してください。"
"35° APIの原油について、Standing、Valko-McCain、Velardeのバブルポイント圧力を比較してください。"

油井性能分析

"初期圧力4000 psia、バブルポイント圧力3500 psia、38° APIの原油、温度175°F、有効層厚75 ft、浸透率150 mD、表皮係数 -2、排水半径1500 ft、井半径0.5 ftの油井のIPR曲線を生成してください。"
"同じ油井について、流動圧力2000 psiaでの原油生産速度を計算してください。"
"浸透率が生産にどのように影響するかを示してください - 50、100、150、200、250 mDでテストしてください。"

シミュレーション準備

"Corey相関式を使用して、25行のSWOF相対浸透率テーブルを生成してください。最大油相相対浸透率1.0、最大水相相対浸透率0.25、束縛水飽和度0.15、残留油飽和度0.15、油相指数2.5、水相指数1.5。"
"無次元半径10.0の帯水層影響関数を作成してください。"
"38° APIの原油について、175°F、500から5000 psiaのブラックオイルテーブルを生成してください。"

油層不均質性

"Lorenz係数0.5をDykstra-Parsonsベータパラメータに変換してください。"
"Lorenz係数0.6、10層、平均浸透率100 mDの層浸透率分布を生成してください。"

多段階ワークフロー

"38° APIの原油について、175°F、初期圧力4000 psiaの条件で、完全な油層分析を実行してください。バブルポイントを計算し、PVTテーブルを生成し、IPR曲線を作成し、油井性能を分析してください。"
"油井の仕上げを設計してください。最適な流動圧力を計算し、IPRを生成し、異なる表皮係数を比較してください。"
"ガス層を評価してください。臨界物性を計算し、IPRを生成し、異なるZ係数の計算方法を比較してください。"

高度なクエリ

• 詳細なPVTワークフロー、ガス分析、油井性能とIPR、感度分析、ブラインとCO₂貯留、油層不均質性、相挙動とフラッシュ計算、成分ライブラリ、経済と最適化、比較とベンチマーキング、教育的なクエリ、トラブルシューティングと検証など、多様なクエリ例があります。

ユニットシステム

すべての計算は、業界標準に基づく現場単位（米国油田単位） を使用します:

Claudeに "pyRestToolboxはどのような単位を使用していますか？" と尋ねることで、完全な単位ドキュメントにアクセスできます。

アーキテクチャ

プロジェクト構造

pyrestoolbox-mcp/
├── src/pyrestoolbox_mcp/
│   ├── server.py              # メインのMCPサーバー (FastMCP)
│   ├── config.py              # サーバー設定と定数
│   ├── tools/                 # 47のMCPツールの実装 (~13,800 LOC)
│   │   ├── 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. ツール層 - pyRestToolboxの計算をラップする47の関数。
4. pyRestToolbox - 実際の油層工学計算を実行します。
5. 型変換 - JSON用のnumpy/pandas/mpmathのシリアライズを処理します。

ツールカテゴリ

🔧 技術詳細

利用可能な計算方法

原油相関式

バブルポイント圧力

• 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係数

• 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 General Public License v3.0 (GPL-3.0)

このMCPサーバーは、pyResToolboxに基づいて構築されており、GPL-3.0ライセンスの下で提供されています。このプロジェクトは、GPL-3.0ライセンスの条件に完全に準拠しています。

要点:

• 無料でオープンソースのソフトウェア
• GPL-3.0の条件の下で使用、変更、配布できます。
• 変更内容もGPL-3.0の下で公開する必要があります。
• 保証は提供されません (詳細はLICENSEを参照)
• GPL-3.0の条件の下で商用利用が許可されています。

完全なライセンステキストはLICENSEを参照してください。