Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@heatpump-mcp-server Size a heat pump for my 2000 sq ft home in 02138"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server for residential heat pump sizing, cost estimation, and cold-climate performance verification. Use with AI assistants like Claude Desktop, Claude Code, Cursor, and other MCP clients.
Works out-of-the-box with bundled data - no API keys required!
The server runs directly via uvx - no installation required. Your MCP client will handle this automatically.
Choose your preferred AI assistant:
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %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"]
}
}
}Restart Claude Desktop.
Add to .claude/mcp.json in your workspace:
{
"mcpServers": {
"heatpump-calculator": {
"command": "uvx",
"args": ["--refresh", "--from", "git+https://github.com/subspace-lab/heatpump-mcp-server.git", "heatpump-mcp-server"]
}
}
}Restart VS Code.
Add to Cursor's MCP settings (Settings > MCP):
{
"mcpServers": {
"heatpump-calculator": {
"command": "uvx",
"args": ["--refresh", "--from", "git+https://github.com/subspace-lab/heatpump-mcp-server.git", "heatpump-mcp-server"]
}
}
}Restart Cursor.
Any MCP-compatible client can use:
{
"mcpServers": {
"heatpump-calculator": {
"command": "uvx",
"args": ["--refresh", "--from", "git+https://github.com/subspace-lab/heatpump-mcp-server.git", "heatpump-mcp-server"]
}
}
}That's it! The server includes:
81 heat pump models from major manufacturers
2024 state-average electricity rates for all US states
TMY3 weather station data for climate zones
No API keys needed to get started.
Related MCP server: EnergyAI MCP
calculate_heat_pump_sizing: Single-zone BTU sizing with humidity considerations
calculate_multi_zone_sizing: Floor-by-floor load calculations for complex homes
estimate_energy_costs: Bill comparison and 10-year payback analysis
check_cold_climate_performance: Verify capacity at design temperature
get_electricity_rate: Fetch current electricity rates by ZIP code
list_heat_pump_models: Browse 81 heat pump models with specs
design-temps/{zip_code}: Climate data and design temperatures
heat-pump-models: Complete model database with BTU, HSPF2, prices
climate-zones: ASHRAE climate zone reference
size-heat-pump: Step-by-step sizing guidance
analyze-costs: Cost comparison workflow
verify-cold-climate: Cold climate suitability check
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...For more accurate electricity rates, you can optionally provide an EIA API key:
Get a free EIA API key: https://www.eia.gov/opendata/register.php
Add to your MCP client config:
{
"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"
}
}
}
}Or create a .env file in your working directory:
# Optional: For live electricity rate lookups
EIA_API_KEY=your_eia_api_key_hereNote: Without an API key, the server uses 2024 state-average electricity rates, which are generally accurate for cost estimates.
git clone https://github.com/subspace-lab/heatpump-mcp-server.git
cd heatpump-mcp-server
uv pip install -e .If you prefer to install the package locally instead of using 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"
}
}
}Note: Using uvx with --refresh is recommended for most users as it automatically updates to the latest version.
Built on FastMCP for easy MCP server development.
Heat Pump Models: Bundled database of 81 models (Mitsubishi, Fujitsu, Daikin, LG, etc.)
Climate Data: TMY3 weather station database with design temperatures
Electricity Rates: Bundled 2024 state averages (EIA API optional for live data)
Sizing: Climate-zone specific BTU/sqft coefficients based on building age and insulation
Costs: Monthly degree-day analysis with heat pump COP curves
Cold Climate: Manufacturer capacity curves with temperature derating
# 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.mdContributions welcome! Areas for improvement:
Additional heat pump models
More weather stations for better coverage
Manual J load calculation support
International climate zone support
MIT License - see LICENSE file for details.
Climate data from EEWeather
Heat pump specs compiled from manufacturer data
Built with FastMCP
Electricity rate fallbacks from EIA
Calculate required BTU capacity for a single-zone heat pump installation.
This tool performs a quick sizing calculation based on:
Home location (ZIP code) for climate zone and design temperature
Square footage and building age for heat loss estimation
Optional humidity considerations for enhanced dehumidification needs
Returns: Dictionary with: - required_btu: Recommended BTU capacity - btu_range_min/max: Acceptable range for equipment selection - design_temperature: Design heating temperature for location - climate_zone: ASHRAE climate zone - recommended_models: List of suitable heat pump models - calculation_notes: Detailed explanation of calculations - humidity_recommendations: Optional humidity control advice - oversizing_warnings: Warnings if system may be oversized
Inputs: zip_code (required), square_feet (required), build_year (required), humidity_concerns, +2 more. Returns: object
Calculate heating/cooling loads for a multi-zone home with detailed zone-by-zone analysis.
Each zone should specify:
name: User-defined zone name
square_feet: Zone area (50-5000 sqft)
ceiling_height: Height in feet (7-20 ft, default 8)
zone_type: living_area, bedrooms, kitchen, basement, attic, garage, other
sun_exposure: north, south, east, west, minimal
window_coverage: Percentage of wall area as windows (0.0-0.5, default 0.15)
occupancy: high, medium, low
heat_sources: List like ["kitchen_appliances", "electronics", "home_office"]
air_sealing: tight, average, leaky
is_above_grade: True if above ground level
Returns: Dictionary with: - total_cooling_load/total_heating_load: Total BTU requirements - zone_results: Detailed results for each zone - system_options: Recommended multi-zone configurations - climate_info: Location-specific climate data - recommendations: Installation and design recommendations
Inputs: zip_code (required), build_year (required), zones (required). Returns: object
Verify heat pump performance at design temperature and determine backup heat requirements.
Analyzes:
Heat pump capacity at design temperature (coldest expected outdoor temp)
Percentage of heating load covered by heat pump alone
Required backup heat capacity to cover shortfall
Temperature range where heat pump provides full heating
COP (efficiency) across temperature range
Critical for cold-climate installations to ensure adequate heating on coldest days.
Returns: Dictionary with: - location_info: Climate zone and design conditions - heat_pump_model: Selected model name - capacity_curve: Heat pump capacity at various outdoor temperatures - performance_analysis: Coverage at design temp, backup heat needed - backup_heat_recommendation: Recommended backup system if needed - temperature_range_analysis: Performance across temperature ranges - key_findings: Important observations - warnings: Critical issues or limitations
Inputs: zip_code (required), square_feet (required), build_year (required), heat_pump_model (required), +1 more. Returns: object
Estimate annual electricity costs and payback period for heat pump vs current heating system.
Analyzes:
Monthly heating load based on location and home characteristics
Heat pump electricity consumption using model's efficiency (HSPF2)
Comparison with current heating fuel costs
10-year cost projection with savings analysis
Break-even year calculation
Returns: Dictionary with: - location_info: Climate and location details - electricity_rate: Rate used for calculations ($/kWh) - gas_rate: Comparison fuel rate if applicable - heat_pump_info: Selected model specifications - monthly_breakdown: Month-by-month cost comparison - annual_summary: Annual totals and payback analysis - ten_year_projection: Long-term savings projection - calculation_notes: Important assumptions and notes
Inputs: zip_code (required), square_feet (required), build_year (required), heat_pump_model (required), +3 more. Returns: object
Get the current electricity rate for a specific ZIP code location.
Fetches residential electricity rates from EIA (Energy Information Administration) API. Requires EIA_API_KEY environment variable to be set.
Returns: Dictionary with: - zip_code: Input ZIP code - electricity_rate: Rate in $/kWh - unit: Always "$/kWh" - source: Data source information
Inputs: zip_code (required). Returns: object
List available heat pump models, optionally filtered by brand, capacity, or efficiency.
Returns comprehensive database of heat pump models with:
Brand and model name
BTU capacity (heating/cooling)
HSPF2 efficiency rating (higher is more efficient)
Estimated price range
Filters:
brand: Case-insensitive partial match (e.g., "Mitsubishi", "Fujitsu")
min_btu/max_btu: Capacity range for sizing
min_hspf2: Minimum efficiency threshold (typical range: 8.0-12.0)
Returns: Dictionary with: - total_models: Count of models matching filters - brands: List of available brands - models: List of model details
Inputs: brand, min_btu, max_btu, min_hspf2. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
Scored across 6 tools
Each tool has a clearly distinct purpose: single-zone sizing, multi-zone sizing, cold-climate performance verification, energy cost estimation, electricity rate lookup, and model listing. There is no overlap or ambiguity between tools.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., calculate_heat_pump_sizing, list_heat_pump_models), making the naming predictable and easy to understand.
With 6 tools covering core aspects of heat pump sizing and analysis, the count is well-scoped. Each tool serves a necessary function without redundancy or unnecessary complexity.
The tool surface covers major workflows: sizing (single and multi-zone), cold climate performance, cost estimation, and model listing. Minor gaps exist, such as no direct tool for comparing models or generating full reports, but these are not critical for the domain.
Solar, weatherization, EV charging, battery and heat-pump decision tools for AI agents.
Heating, ventilation and energy engineering calculations and diagnostics for AI agents.
Pipe sizing, heat loss, gas record checks and emergency triage for UK plumbers' AI assistants
Home energy for AI assistants: live Power flow, Energy history, solar forecast, and device control.
