heatpump-mcp-server

Name: heatpump-mcp-server
Availability: InStock
Author: Weiqi

Open-source MCP server for HeatPumpHQ API - provides heat pump sizing, cost estimation, and performance analysis tools for Claude

GitHub 公式サイト

GitHubスター

ユーザー評価

未評価

フォーク

イシュー

閲覧数

お気に入り

README

🏠 HeatPumpHQ MCP Server

An MCP (Model Context Protocol) server that brings professional heat pump sizing, cost analysis, and performance verification directly to Claude. Get instant heat pump calculations, cost estimates, and cold-climate suitability analysis through natural conversation.

🚀 NEW: Zero-Setup Hosted Version Available! Most users should use our hosted MCP server at https://mcp.wattsavy.com/mcp - no Python installation required!

🚀 Quick Start

No installation required! Connect directly to our hosted MCP server:

For Claude Desktop:

Add to Claude Desktop config:

{
  "mcpServers": {
    "heatpump": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch", "https://mcp.wattsavy.com/mcp"]
    }
  }
}

For Claude Code:

Run the following command to install the MCP server:

claude mcp add --transport http heatpump https://mcp.wattsavy.com/mcp

Start calculating immediately! Ask Claude:

"Help me size a heat pump for my 2000 sq ft home in Boston"

🛠️ What You Can Do

🏠 Quick Sizing

Get instant BTU requirements and equipment recommendations:

Accounts for climate zone, home age, and square footage
Returns specific heat pump models with efficiency ratings
Considers single-zone and multi-zone configurations

💰 Cost & Savings Analysis

Calculate 10-year cost projections and payback periods:

Compare heat pump vs. current heating (gas, oil, electric)
Real electricity rates and regional cost factors
Monthly breakdown with seasonal variations

❄️ Cold Climate Performance

Verify heat pump viability in harsh winters:

Capacity curves at design temperatures
Backup heat requirements and recommendations
Performance analysis down to -15°F and below

🔧 Installation Cost Estimation

Get comprehensive project cost breakdowns:

Regional labor rates and permit costs
Complexity assessment (ductwork, electrical, etc.)
Rebate and incentive information

🌟 Why Use This MCP Server?

✅ Zero Setup Benefits

No Python installation - Works immediately with any Claude Desktop setup
No dependency management - No need to install packages or manage environments
Auto-updated - Always uses the latest features and fixes
High reliability - 99.9% uptime with professional hosting
Better performance - Dedicated server infrastructure

📋 Prerequisites

Claude Desktop or Claude Code - That's it! No other requirements.

🏗️ Architecture Overview

This project provides two MCP server implementations:

🌐 HTTP Server (server_http.py) - For hosted/remote access
- Deployed at: https://mcp.wattsavy.com/mcp
- Protocol: HTTP POST + Server-Sent Events (SSE)
- Use case: Zero-setup remote access via @modelcontextprotocol/server-fetch
💻 FastMCP Server (server.py) - For local installation
- Protocol: JSON-RPC over stdio
- Use case: Local development, offline access, customization

✅ Verify Installation

Test the connection by asking Claude: "What tools are available for heat pump calculations?"

⚙️ Configuration

Configuration File Locations

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

🎯 Usage Examples

Ask Claude natural questions like:

Sizing Questions

"What size heat pump do I need for a 1800 sq ft ranch built in 1995 in Denver?"
"Help me size equipment for a 3-story home in climate zone 6A"

Cost Analysis

"Compare the 10-year costs of keeping my gas furnace vs switching to a Mitsubishi heat pump"
"What's the payback period for heat pump conversion in my area?"

Cold Climate Suitability

"Will heat pumps work in Minnesota winters for my 2500 sq ft home?"
"At what temperature would I need backup heat with a Daikin cold-climate unit?"

Installation Planning

"Estimate total installation costs including electrical upgrades and permits"
"What factors affect heat pump installation complexity?"

🧪 Testing

Verify everything is working:

# Full test suite (recommended)
uv run python test_e2e.py --env production

# Basic functionality test
uv run python test_server.py

# Test specific environments
uv run python test_e2e.py --env local        # Local development
uv run python test_e2e.py --env production   # Production API

🏗️ API Reference

Tools Available

Tool	Purpose	Key Parameters
`quick_sizer`	Calculate BTU requirements	ZIP code, sq ft, build year
`bill_estimator`	Cost analysis & ROI	Home details, heat pump model, current fuel
`cold_climate_check`	Cold weather performance	Location, equipment model, backup heating
`project_cost_estimator`	Installation cost breakdown	Site complexity, regional factors

Resources Available

Resource	Purpose
`heatpump://api-status`	Real-time backend health check
`heatpump://endpoints`	List of available calculation tools

🔧 Development & Local Installation

For developers who want to modify the server or need offline access:

Local Installation

# Clone and set up
git clone https://github.com/jiweiqi/heatpump-mcp-server.git
cd heatpump-mcp-server
uv sync  # or pip install -r requirements.txt

# Test the installation
uv run python test_e2e.py --env production

Local Configuration

For Claude Desktop:

{
  "mcpServers": {
    "heatpump": {
      "command": "uv",
      "args": [
        "--directory", 
        "/absolute/path/to/heatpump-mcp-server", 
        "run", 
        "python", 
        "server.py"
      ],
      "env": {
        "ENV_MODE": "production"
      }
    }
  }
}

For Claude Code:

claude mcp add --transport stdio heatpump "uv --directory /absolute/path/to/heatpump-mcp-server run python server.py"

Environment Configuration

# Copy example configuration
cp .env.example .env

# For local development (optional)
# Edit .env to point to your local backend
HEATPUMP_API_URL=http://localhost:8000

Prerequisites for Local Installation

Python 3.8+
uv (recommended) or pip package manager
Claude Desktop or Claude Code

Project Structure

heatpump-mcp-server/
├── server.py              # FastMCP server (local/stdio)
├── server_http.py          # HTTP+SSE server (hosted)
├── test_e2e.py            # Comprehensive test suite
├── test_server.py          # Basic functionality tests
├── run_tests.sh           # Test runner script
├── Dockerfile             # Docker container config
├── requirements.txt        # Python dependencies
├── pyproject.toml         # Python project config
├── uv.lock                # UV lock file
├── LICENSE                # MIT license
└── README.md              # This documentation