JinDaGe - pyrestoolbox-mcp MCP Details

article

README

🚀 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₂ 封存、油藏非均质性、相态行为与闪蒸计算、组分库、经济与优化、比较与基准测试、教育查询、故障排除与验证等方面的查询示例。

查询提示

💡 使用建议

具体明确：包含所有相关参数（API、温度、压力等）。

指定方法：提及你想要使用的关联式（VALMC、DAK、Corey、LET 等）。

包含单位：始终指定单位（psia、degF、mD、ft 等）。

请求比较：要求比较不同方法或场景。

请求表格：当需要多个值时，请求以表格形式呈现结果。

跟进问题：基于之前的答案进行复杂工作流的查询。

单位系统

所有计算均遵循行业标准，使用 油田单位制（美国油田）： | 属性 | 单位 | 示例 | |------|------|---------| | 压力 | 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        # 多传输方式部署

工作原理

FastMCP 服务器：处理 MCP 协议通信（STDIO、HTTP、SSE）。
Pydantic 模型：验证所有输入并提供描述性错误信息。
工具层：47 个函数封装了 pyrestoolbox 的计算功能。
pyRestToolbox：执行实际的油藏工程计算。
类型转换：处理 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）。
增强的类型提示。
额外的验证实用工具。

致谢

本项目的实现离不开以下人员和组织的贡献：

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 · 请求功能 · 文档 · 示例

pyrestoolbox-mcp

README

🚀 pyResToolbox MCP Server

🚀 快速开始

安装

连接到 Claude Desktop

首次查询

✨ 主要特性

📦 安装指南

安装依赖

连接到 Claude Desktop

💻 使用示例

基础用法

高级用法

📚 详细文档

可以进行的操作

原油 PVT 分析

天然气 PVT 分析

油井性能与流入动态关系（IPR）

油藏模拟支持

高级计算

配置与帮助

给 Claude 的示例查询

基本 PVT 计算

油井性能分析

模拟准备

油藏非均质性

多步骤工作流

高级查询

查询提示

单位系统

项目架构

项目结构

工作原理

工具分类

🔧 技术细节

可用的计算方法

原油关联式

天然气关联式

相对渗透率

📄 许可证

项目状态

版本历史

路线图

计划功能

上游集成

相关项目

核心依赖

类似的 MCP 服务器

石油工程工具

致谢

引用

支持

获取帮助

社区

⭐ 给项目加星

☕ 请我喝咖啡

📈 加星历史

Runtime guide

Hosted runtime

Local runtime / other methods