Overview

HeatPump MCP Server is a developer-focused service that provides fast, reproducible residential heat-pump sizing and cost estimates. It implements a Model Context Protocol (MCP) server model designed to accept building and climate inputs, run deterministic sizing/cost logic, and return structured, machine-readable recommendations suitable for integration with web apps, quoting tools, or LLM-based assistants.

The server is intended for engineers, HVAC integrators, and software teams who need programmatic access to home-system recommendations—covering heat-pump capacity selection, estimated installation costs, and breakdowns by equipment and labor. By exposing a lightweight API and well-documented JSON schemas, HeatPump MCP Server makes it straightforward to embed conservative, auditable estimates into pipelines and UIs.

Features

Programmatic sizing engine for residential heat-pump systems
Cost estimation with equipment, labor, and optional incentives
JSON input/output suitable for LLMs, automation, and dashboards
OpenAPI / schema-driven endpoints for easy integration
Local development with Docker and quick start scripts
Test harness and sample datasets for validation
Configurable climate and pricing models for regional tuning

Installation / Configuration

Clone the repository, create a Python virtual environment, and install dependencies. The example below assumes a typical Python/FastAPI stack and uses uvicorn to run the server locally.

# Clone repository
git clone https://github.com/jiweiqi/heatpump-mcp-server.git
cd heatpump-mcp-server

# Create and activate virtual environment (macOS/Linux)
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the server locally
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Environment variables (examples; adapt to your deployment):

# Example environment variables
export HP_MCP_LOG_LEVEL=info
export HP_MCP_PORT=8000
export HP_MCP_PRICING_MODEL=default
export HP_MCP_CLIMATE_DATA=/data/climate_zones.json

Docker quickstart:

# Build and run with Docker
docker build -t heatpump-mcp-server .
docker run -p 8000:8000 --env-file .env heatpump-mcp-server

Available Tools / Resources

OpenAPI (Swagger) UI: /docs (auto-generated API documentation)
Example input JSON files: /examples/
Sample climate zones and price tables: /data/
Unit and integration tests: /tests/
Dockerfile and deployment manifests: /deploy/
GitHub source and issue tracker: https://github.com/jiweiqi/heatpump-mcp-server

API Primer

Common endpoints (typical names; consult OpenAPI for exact paths):

GET /health — server health check
POST /estimate — get sizing and cost recommendation
POST /batch-estimate — batch processing for multiple homes
GET /pricing-models — list available pricing/climate models

Example request to /estimate:

POST /estimate
Content-Type: application/json

{
  "address": "123 Main St",
  "climate_zone": "4A",
  "floor_area_sqft": 1800,
  "num_bedrooms": 3,
  "insulation_level": "moderate",
  "existing_system": "electric_furnace",
  "preferences": {
    "max_budget": 15000,
    "noise_preference": "low"
  }
}

Example response:

{
  "recommended_capacity_tons": 3.0,
  "equipment": {
    "model": "HPX-3.0",
    "efficiency_seer": 18,
    "unit_cost": 7000
  },
  "labor_estimate": 3000,
  "incentives": 1200,
  "total_estimated_cost": 8800,
  "notes": "Sizing assumes moderate insulation and typical infiltration rates for climate zone 4A."
}

Input and output follow JSON schemas in /schemas/ to facilitate validation and integration.

Use Cases

HVAC Contractor Quoting
- A contractor integrates /estimate into their quoting app. Sales staff fill a simple form (address, sq.ft., insulation), call the API, and receive a recommended heat-pump capacity and line-item cost estimate to present to customers.
Homebuyer Planning
- A residential energy advisor or homebuyer tool uses the server to compare upgrade scenarios (replace existing electric furnace vs. heat-pump retrofit). The tool performs batch requests for multiple homes in a neighborhood to estimate program budget needs.
Utility Program Analysis
- A utility running an incentive program uses the batch-estimate endpoint to process CSV exports of customer homes and generate total expected incentives, equipment demand, and installation capacity requirements.
LLM-enabled Assistant
- Integrate the MCP server with an LLM workflow to provide grounded, auditable numerical recommendations that the assistant can cite when advising users about system size and cost.

Tips for Developers

Validate inputs against the provided JSON schemas before calling /estimate to ensure deterministic behavior.
Use the provided pricing models and climate data for baseline estimates; override with regional cost tables for more accuracy.
Run unit tests in /tests/ when updating sizing logic to avoid regressions.
Check /docs (OpenAPI) to discover any optional flags (e.g., conservative sizing, expedited install) that affect outputs.

For full source, issues, and contribution guidelines, see the GitHub repository: https://github.com/jiweiqi/heatpump-mcp-server.

HeatPump MCP Server: Residential Sizing & Cost Estimator