heatpump

HeatPump MCP Server provides a ready-to-use MCP service for residential heat pump sizing, cost estimation, and cold-climate performance verification. It ships with 81 bundled heat pump models, 2024 state-average electricity rates, and TMY3 weather data, so you can perform end-to-end analyses without external APIs keys. To use it, configure your MCP client to point at the heatpump-mcp-server via uvx, then invoke the built-in tools such as sizing and cost analysis. Tools include calculate_heat_pump_sizing for single-zone sizing with humidity considerations, calculate_multi_zone_sizing for floor-by-floor loads, estimate_energy_costs for bill comparisons and payback, check_cold_climate_performance to verify capacity at design temperatures, get_electricity_rate for rate lookups by ZIP, and list_heat_pump_models to browse the 81 models. The server also exposes data endpoints like design-temps/{zip_code}, heat-pump-models, and climate-zones for reference during analyses. Guided workflows via prompts help structure sizing, cost analysis, and cold-climate verification steps within your MCP client.

Prerequisites:

• Node.js environment is not required for this server; it runs with uvx (Python). Ensure you have uvx installed and accessible in your PATH. You may also use a compatible MCP client capable of launching external MCP servers.

1. Install uvx (Python Virtual Environment or globally, per your preference):

• Follow installation instructions from the uvx project (typically via pip or homebrew if available in your environment).

2. Run the server directly (no install needed):

• The server is designed to run via uvx with the provided configuration. A minimal run example is:

uvx --refresh --from git+https://github.com/subspace-lab/heatpump-mcp-server.git heatpump-mcp-server

3. Configure your MCP client to connect to the server:

• Example client configuration (adapt to your client format):

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

4. Optional: provide live electricity rate data by setting EIA API key:

• Environment variable (within 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"
      }
    }
  }
}

5. Local installation alternative (if you prefer to install the package locally):

• Install the package with uvx and run the server name directly as shown in the README, then configure your MCP client to use the local command:

# 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.

Tips and caveats:

• No API keys are required for the bundled data; the EIA API key is optional for live electricity rate data. Without a key, the server uses 2024 state-average rates.
• The server pulls the latest code via --refresh from the heatpump-mcp-server GitHub repository, ensuring you have the most up-to-date models and features.
• Data sources include 81 bundled heat pump models, TMY3 weather data, and climate-zone references. If you need more models or weather stations, consider updating the bundled data or using live data sources via the EIA API key.
• This MCP server is built on FastMCP, so expect standard FastMCP behaviors and tool invocation semantics. Use the list_heat_pump_models tool to explore the model database before running sizing or cost analyses.