热泵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-zonesASHRAE气候区参考
💡 提示（引导式工作流）
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密钥：
- 获取免费的EIA API密钥：https://www.eia.gov/opendata/register.php
- 在您的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 文件。
致谢
- 来自气候数据的 EEWeather（可译为“EE天气”）
- 根据制造商数据整理的热泵规格
- 用……建造 FastMCP
- 电力费率的回退机制 EIA（Environmental Impact Assessment）翻译为中文是“环境影响评估”
支持
- 问题链接：https://github.com/subspace-lab/heatpump-mcp-server/issues
- 讨论链接：https://github.com/subspace-lab/heatpump-mcp-server/discussions