AI导哈

热泵计算服务

用于住宅热泵尺寸计算、成本估算和寒冷气候性能验证的模型上下文协议（MCP）服务器，可与AI助手集成使用。

  • by jiweiqi
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 jiweiqi/heatpump-mcp-server

使用说明

热泵MCP服务器

一个用于住宅热泵选型、成本估算及寒冷气候性能验证的模型上下文协议（MCP）服务器。可与Claude Desktop、Claude Code、Cursor等AI助手及其他MCP客户端配合使用。

开箱即用，内置数据 - 无需API密钥！

快速入门

1. 无需安装！

服务器直接通过（某种方式）运行 uvx - 无需安装。您的MCP客户端将自动处理此事。

2. 配置您的MCP客户端

选择您偏好的AI助手：

Claude Desktop (Anthropic)

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "heatpump-calculator": {
      "command": "uvx",
      "args": ["--refresh", "--from", "git+https://github.com/subspace-lab/heatpump-mcp-server.git", "heatpump-mcp-server"]
    }
  }
}

重启Claude桌面版。

Claude Code (VS Code Extension)

添加到 .claude/mcp.json 在你的工作区中：

{
  "mcpServers": {
    "heatpump-calculator": {
      "command": "uvx",
      "args": ["--refresh", "--from", "git+https://github.com/subspace-lab/heatpump-mcp-server.git", "heatpump-mcp-server"]
    }
  }
}

重启 VS Code。

Cursor (AI Code Editor)

添加到 Cursor 的 MCP 设置中（设置 > MCP）：

{
  "mcpServers": {
    "heatpump-calculator": {
      "command": "uvx",
      "args": ["--refresh", "--from", "git+https://github.com/subspace-lab/heatpump-mcp-server.git", "heatpump-mcp-server"]
    }
  }
}

重启光标。

Other MCP Clients

任何兼容MCP的客户端都可以使用：

{
  "mcpServers": {
    "heatpump-calculator": {
      "command": "uvx",
      "args": ["--refresh", "--from", "git+https://github.com/subspace-lab/heatpump-mcp-server.git", "heatpump-mcp-server"]
    }
  }
}

3. 开始使用

就是这些！服务器包括：

  • 来自各大制造商的81款热泵型号
  • 2024年美国各州平均电价
  • 气候区的TMY3气象站数据

无需API密钥即可开始。

特点

🔧 工具（计算器）

  • **calculate_heat_pump_sizing**考虑湿度因素的单区BTU（英热单位）容量计算
  • **calculate_multi_zone_sizing**复杂住宅的逐层负荷计算
  • **estimate_energy_costs**账单对比与10年回报分析
  • **check_cold_climate_performance**验证设计温度下的容量
  • **get_electricity_rate**根据邮政编码查询当前电费率
  • **list_heat_pump_models**浏览81款带规格的热泵型号

📚 资源（数据访问）

  • **design-temps/{zip_code}**气候数据和设计温度
  • **heat-pump-models**完整的模型数据库，包含BTU（英热单位）、HSPF2（季节性能效比2）及价格信息
  • **climate-zones**ASHRAE气候区参考

💡 提示（引导式工作流）

  • **size-heat-pump**逐步尺寸选择指南
  • **analyze-costs**成本比较工作流程
  • **verify-cold-climate**寒冷气候适宜性检查

示例交互

选择合适的热泵

User: I need help sizing a heat pump for my 2000 sq ft home built in 1995 in ZIP 02138.

AI: [Uses calculate_heat_pump_sizing tool]
Based on your location (Cambridge, MA - Climate Zone 5A) and home characteristics:
- Required BTU: 80,000 BTU
- Recommended range: 72,000 - 88,000 BTU
- Design temperature: 6°F
...

成本分析

User: What would a Mitsubishi MXZ-3C30NA cost to operate vs my gas furnace?

AI: [Uses estimate_energy_costs tool]
Annual cost comparison:
- Heat pump: $1,850/year (using bundled state average rate)
- Gas furnace: $2,400/year
- Annual savings: $550
- Payback period: 8.2 years
...

寒冷气候验证

User: Will a Fujitsu AOU24RLXFZ work in Minneapolis?

AI: [Uses check_cold_climate_performance tool]
Cold climate analysis:
- Design temp: -13°F
- Heat pump capacity at design: 18,000 BTU
- Your heating load: 75,000 BTU
- Coverage: 24% (Inadequate)
- Recommendation: You'll need substantial backup heat...

高级配置

可选：实时电价数据

如需获取更准确的电费费率，您可以选择提供一个EIA API密钥：

  1. 获取免费的EIA API密钥：https://www.eia.gov/opendata/register.php

  2. 在您的MCP客户端配置中添加：

{
  "mcpServers": {
    "heatpump-calculator": {
      "command": "uvx",
      "args": ["--refresh", "--from", "git+https://github.com/subspace-lab/heatpump-mcp-server.git", "heatpump-mcp-server"],
      "env": {
        "EIA_API_KEY": "your_eia_api_key_here"
      }
    }
  }
}

或者创建一个 .env 在你的工作目录中找到文件：

# Optional: For live electricity rate lookups
EIA_API_KEY=your_eia_api_key_here

注如果没有API密钥，服务器将使用2024年的平均电力费率，这些费率通常用于准确估算成本。

从源代码安装

用于开发或定制

git clone https://github.com/subspace-lab/heatpump-mcp-server.git
cd heatpump-mcp-server
uv pip install -e .

对于本地安装（高级）

如果你更倾向于在本地安装这个包，而不是使用 uvx：

# Install from GitHub
uv pip install git+https://github.com/subspace-lab/heatpump-mcp-server.git

# Then configure your MCP client to use the local installation:
{
  "mcpServers": {
    "heatpump-calculator": {
      "command": "heatpump-mcp-server"
    }
  }
}

注：使用 uvx 和；与 --refresh 建议大多数用户使用，因为它会自动更新到最新版本。

建筑学

建立在 FastMCP 便于MCP服务器的开发。

数据来源

  • 热泵型号包含81个模型（三菱、富士通、大金、LG等）的数据库包
  • 气候数据含设计温度的TMY3天气站数据库
  • 电价根据上述信息，执行如下指令：作为专业翻译，负责将英语内容翻译成中文内容，请帮我翻译以下原文内容

计算方法

  • **定型处理（或 sizing，根据上下文可能指纺织品加工中的上浆处理）**基于建筑年代和保温性能的气候区特定BTU/平方英尺系数
  • 成本月度度日分析结合热泵能效比曲线
  • 寒冷气候制造商的容量曲线，考虑温度降额因素

发展

设置开发环境

# Clone repo
git clone https://github.com/subspace-lab/heatpump-mcp-server.git
cd heatpump-mcp-server

# Install with dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Lint code
ruff check .

项目结构

heatpump_mcp_server/
├── src/heatpump_mcp_server/
│   ├── server.py          # Main MCP server
│   ├── tools.py           # Calculator tools
│   ├── resources.py       # Data resources
│   ├── prompts.py         # Guided prompts
│   ├── config.py          # Configuration
│   ├── models/            # Pydantic models
│   └── services/          # Business logic
│       ├── quick_sizer_service.py
│       ├── bill_estimator_service.py
│       ├── cold_climate_service.py
│       └── ...
├── data/                  # Bundled data files
│   ├── hpmodels.json      # 81 heat pump models
│   └── eeweather_stations.json  # Weather data
├── tests/
├── pyproject.toml
└── README.md

贡献

欢迎贡献！改进方向：

  • 额外的热泵型号
  • 增设更多气象站以实现更全面的覆盖
  • 手动J负荷计算支持
  • 国际气候区支持

许可证

MIT 许可证 - 详情请参见 LICENSE 文件。

致谢

支持

  • 问题链接：https://github.com/subspace-lab/heatpump-mcp-server/issues
  • 讨论链接：https://github.com/subspace-lab/heatpump-mcp-server/discussions

相关 MCP