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!
No installation required! Connect directly to our hosted MCP server:
- Add to Claude Desktop config:
{ "mcpServers": { "heatpump": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-fetch", "https://mcp.wattsavy.com/mcp"] } } }
-
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"
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
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
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
Get comprehensive project cost breakdowns:
- Regional labor rates and permit costs
- Complexity assessment (ductwork, electrical, etc.)
- Rebate and incentive information
- 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
- Claude Desktop or Claude Code - That's it! No other requirements.
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
- Deployed at:
-
💻 FastMCP Server (
server.py
) - For local installation- Protocol: JSON-RPC over stdio
- Use case: Local development, offline access, customization
Test the connection by asking Claude: "What tools are available for heat pump calculations?"
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Ask Claude natural questions like:
- "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"
- "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?"
- "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?"
- "Estimate total installation costs including electrical upgrades and permits"
- "What factors affect heat pump installation complexity?"
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
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 |
Resource | Purpose |
---|---|
heatpump://api-status |
Real-time backend health check |
heatpump://endpoints |
List of available calculation tools |
For developers who want to modify the server or need offline access:
# 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
{
"mcpServers": {
"heatpump": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/heatpump-mcp-server",
"run",
"python",
"server.py"
],
"env": {
"ENV_MODE": "production"
}
}
}
}
claude mcp add --transport stdio heatpump "uv --directory /absolute/path/to/heatpump-mcp-server run python server.py"
# 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
- Python 3.8+
- uv (recommended) or pip package manager
- Claude Desktop or Claude Code
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
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature
- Make your changes and add tests
- Run the test suite:
./run_tests.sh
- Commit:
git commit -m 'Add amazing feature'
- Push:
git push origin feature/amazing-feature
- Open a pull request
MIT License - see the LICENSE file for details.
This MCP server is powered by the WattSavy heat pump calculation engine, providing:
- ✅ Real data: 40,000+ ZIP codes, TMY3 weather data, actual equipment models
- ✅ Accurate calculations: Manual J-compliant load calculations
- ✅ Current pricing: Real-time electricity rates via EIA API
- ✅ Professional tools: Used by HVAC contractors and homeowners
- 📖 Documentation: This README and inline code comments
- 🐛 Issues: GitHub Issues
- 💬 Questions: Create a discussion on GitHub
- 🌐 Website: WattSavy.com
- 🚀 NEW: Hosted MCP Server at
https://mcp.wattsavy.com/mcp
- ✅ Zero-setup option - No Python or local installation required
- ✅ Auto-updating - Always uses latest features and bug fixes
- ✅ High reliability - Professional hosting with 99.9% uptime
- ✅ Better performance - Dedicated server infrastructure
- ✅ Updated README - Hosted version now the recommended default
- ✅ Automatic publishing - GitHub Actions auto-publishes on changes
- ✅ Updated for WattSavy production API (api.wattsavy.com)
- ✅ Comprehensive E2E test suite with 100% pass rate
- ✅ Environment-specific configurations (production/local)
- ✅ Enhanced error handling and validation
- ✅ Real-time API status monitoring
- ✅ Updated parameter validation for all endpoints
- Initial release with core calculation tools
- Basic Claude Desktop integration
Made with ❤️ for the heat pump community