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