RoofMeasure MCP

Free EagleView-style satellite roof measurements plus modular Xactimate-style estimating, packaged as an MCP server and CLI for any LLM or agent.

What it measures (from Google Solar API 0.1 m elevation data):

• Total roof area (sq ft and squares) from fitted roof planes, per-facet area, pitch and slope direction

• Ridges, hips, valleys, rakes and eaves: every crease is the analytic intersection of two measured roof planes with its true sloped length; rakes are slope-corrected; eaves are level

• Predominant pitch and areas-per-pitch table

• EagleView-convention waste table (3/12 and steeper area only, columns around the suggested factor, squares rounded up to 1/3) and suggested waste factor calibrated to EagleView reports

• Structure complexity (Simple / Normal / Complex), drip edge, steep-slope split

• Tree-canopy confidence rating (HIGH / MEDIUM / LOW) and Google's own whole-roof area as an independent cross-check

• Detached roofs nearby (garage, shed) reported, and measured as extra structures with include_outbuildings=true

Accuracy against six EagleView Premium Reports (Springfield, MO; primary structure): total area within 1% on simple roofs and +5 to +9% on complex ones; rakes within 1 to 9%; eaves within 4 to 8% (15% low where tree canopy hides a side); ridges+hips within 2 to 15% except where crest blur in the elevation model adds a facet (Fred Eagles: +24%). The engine follows EagleView's conventions: an upper roof's edge over a lower roof counts as an interior eave or rake, the wall junction as flashing / step flashing, waste on 3/12-and-steeper area only. Roofs bordered by tree canopy are flagged LOW confidence and are a lower bound. Our outline matches EagleView's drawn outline within about one foot on the canopy-free houses (verified by overlaying the vectors extracted from their PDFs, see tests/ev_extract.py).

Geometry rules (src/roofmeasure/regularize.py): measured planes are snapped to how US homes are framed before any line is drawn. Every pitched plane faces one of the building's four axis directions (45 degrees only for a bay-sized facet); pitch is a whole x/12 and planes within 1/12 of the wing's pitch take the wing's pitch; a strip between two parallel planes at different heights is a connector facet (hip + valley), a strip between planes at the same height is a blurred shoulder and dissolves. Hips and valleys between equal-pitch planes therefore run at exactly 45 degrees in plan and ridges sit centred, as framed. No gambrels: a same-facing pitch change with no wall between the two parts (break parallel to the ridge, flatter plane above) is one plane. Two same-facing, same-pitch neighbours offset by less than 0.6 m with a continuous surface across their boundary are one plane (a blurred shoulder); a jump in the elevation model there is a wall and stays a step. A side-by-side section at a different pitch on the same slope (Tony Russell's 7/12 insert on a 10/12 roof) is kept and its sides are walls (step flashing), as EagleView draws it.

Framing model (src/roofmeasure/roofgraph.py, v0.4.0): the primary line generator. Instead of intersecting fitted planes, it generates the ridge / hip / valley graph from the eave line the way a framer lays it out: every plane rises from its eave at one pitch, so hips run at 45 degrees from outside corners, valleys run from inside corners to the eaves, ridges sit centred over each wing, a narrower wing's ridge ends where its valleys meet and ties to the main ridge with a short hip (the straight skeleton of the eave polygon, computed with bpypolyskel). The elevation model supplies only what geometry cannot: the pitch (consensus of the fitted planes), gable ends (a tent-shaped height profile along the edge, confirmed by the planes), flat or lower sections (carports, porches, lower wings: cut out as their own level with flashing along the wall), and a fit check. The graph is connected by construction. It is used when the elevation model agrees with it within 24 in at the 90th percentile (18 in rms, 12 in bias); otherwise the report falls back to the plane-intersection wireframe and says so. Validated against 27 production-builder roofs in Buckeye AZ, San Tan Valley AZ and Richmond TX (Solar API tiles): 11 pass the gate with roof plans that match the aerials; the rest fall back, mostly because of jagged footprints, patio covers and undetected gable ends. Dependency: bpypolyskel (GPL, pure Python, installed from GitHub). Blender's mathutils C extension is not required: roofmeasure ships the small subset bpypolyskel needs (src/roofmeasure/_mathutils.py, double precision), so no compiler is needed on macOS or in the Docker image.

Topology rules (wireframe.enforce_topology): every ridge, hip and valley must end where it meets another line. A hip starts at an outline corner and ends at the point that begins a ridge; a valley starts at the eave and ends at a ridge or hip junction; a ridge ends at a hip pair, a valley pair or a gable end. A crease end that dangles inside the roof is extended along its own line (through roof pixels only) until it meets another crease or the outline, up to 3 m (4.5 m for a valley reaching for its eave); a short crease that still touches nothing is dropped. The report notes how many ends were repaired.

Eave and rake ordering margin: outline edges are the least certain lines in satellite elevation data (overhangs, canopy, eave-vs-rake classification at walls), and short drip edge or starter is the expensive error. Reported eave and rake totals are the measured lengths times model.EAVE_RAKE_SAFETY (1.15). The measured values are kept in eaves_measured_ft / rakes_measured_ft, printed on the Length Diagram and Report Summary, and the margin is stated in the notes. Diagram segment labels are measured lengths. Ridges, hips, valleys and areas carry no margin.

What it generates:

• EagleView-layout measurement report PDF: cover, aerial, Length / Pitch / Area / Notes diagrams (EagleView colors, rotated segment labels), per- structure Report Summary (areas per pitch, complexity, waste table, lengths), notice page; plus a Markdown version

• Xactimate-style insurance estimate (.docx) with line items, material sales tax, per-structure summaries, tax recap, and grand total. Fully modular: company name/logo, estimator, homeowner, claim info, pricing rules, tax rate, waste %, component counts, and O&P toggle are all configurable.

Setup

1. Get a free Google Cloud API key with the Geocoding API and Solar API enabled (console.cloud.google.com). The $200/month free credit covers roughly 1,000 roof lookups.

2. Install:

   pip install git+https://github.com/thegimmieapp/roofmeasureMCP.git
   # or from a local clone:
   pip install -e .

3. Set your key:

   export GOOGLE_MAPS_API_KEY="your_key_here"

Related MCP server: EnergyAI MCP

Use as an MCP server (Claude Desktop, Claude Code, Cursor, etc.)

Add to your MCP config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "roofmeasure": {
      "command": "roofmeasure-mcp",
      "env": {
        "GOOGLE_MAPS_API_KEY": "your_key_here",
        "ROOFMEASURE_OUT_DIR": "/path/for/reports",
        "ROOFMEASURE_LOGO": "/path/to/company_logo.png"
      }
    }
  }
}

Claude Code: claude mcp add roofmeasure -e GOOGLE_MAPS_API_KEY=your_key -- roofmeasure-mcp

Tools

The estimate tool enforces contractor intake: if homeowner name or date of loss are missing it returns needs_info so the agent asks the user before generating.

Use from any chat: run it as a remote connector

The plugin above only exists while Claude Desktop is open on the machine that has it installed. To use roof-measure from any claude.ai chat (web, desktop, mobile), run the same server over HTTPS and add it as a custom connector.

1. Deploy (Fly.io shown; any host that runs a Docker container works):

   fly launch --no-deploy --copy-config --name roofmeasure-mcp
   fly volumes create reports --size 1 --region dfw
   fly secrets set GOOGLE_MAPS_API_KEY=... \
       ROOFMEASURE_PATH_SECRET=$(openssl rand -hex 16) \
       ROOFMEASURE_PUBLIC_URL=https://roofmeasure-mcp.fly.dev
   fly deploy

   fly secrets list shows the secret name; keep the value you generated. .github/workflows/fly-deploy.yml redeploys on every push to main once a FLY_API_TOKEN repository secret exists (fly tokens create deploy).

2. In claude.ai: Settings > Connectors > Add custom connector, name it RoofMeasure and paste https://roofmeasure-mcp.fly.dev/<secret>/mcp. No OAuth is configured, so the unguessable path segment is the access control: anyone with the full URL can run measurements on your Google key. Rotate the secret (fly secrets set ROOFMEASURE_PATH_SECRET=...) if it leaks.

3. Enable the connector in a chat. Tool results now carry report_pdf_url / estimate_url download links served from the same app (/<secret>/files/<name>), since the files are no longer on your own disk. GET /health is a public liveness check.

Entry point: roofmeasure-mcp-http (Streamable HTTP, stateless, JSON responses). Environment: PORT, GOOGLE_MAPS_API_KEY, ROOFMEASURE_PATH_SECRET, ROOFMEASURE_PUBLIC_URL, ROOFMEASURE_OUT_DIR.

Use from the command line

roofmeasure measure "3708 Ebony Hollow Pass, Austin, TX 78739"
roofmeasure report  "3708 Ebony Hollow Pass, Austin, TX 78739" -o report.md
roofmeasure estimate "3708 Ebony Hollow Pass, Austin, TX 78739"   # prompts for homeowner, date of loss, claim #

How it works

1. Geocodes the address, pulls Google Solar API buildingInsights and dataLayers (0.1 m/px digital surface model + roof mask GeoTIFFs).

2. Segments the DSM into planar facets (region growing on slope + aspect).

3. Classifies every facet boundary: shared boundaries become ridges, hips, or valleys (by relative elevation and facing); perimeter boundaries become eaves or rakes (by edge direction vs the facet's downslope direction). Sloped edge lengths are slope-corrected in 3D.

4. If high-resolution DSM data is not available for an address, it falls back to roof-segment statistics and clearly flags edge lengths as ESTIMATED.

Accuracy notes

This tool is free and uses the best publicly available elevation data. It is strong on areas, pitch, and squares; edge classification is measured from the DSM but can be affected by tree cover, imagery age, and resolution. Current calibration on five canopy-free EagleView reports (main structure, measured values before the eave/rake margin): area within -1% to +9%; hips within +5% to +9% and valleys within -3% to +25% on three of five; one roof (Fred Eagles) has a crest the elevation model blurs into extra facets, giving hips +30% and valleys +71%; eaves within -7% to +4%; rakes -22% to +7% (so the +15% margin still leaves one roof short on rakes). It does not carry an accuracy guarantee - field verify before ordering material, as you would with any measurement report.

Estimating defaults (all overridable)

• Architectural laminated shingles + synthetic 30# felt only

• 1:1 replacement of existing components

• ~$550/SQ blended target across core roofing components (shingle unit price back-solved)

• Steep-roof labor surcharges at 8/12-9/12 and 10/12+ tiers from the measured pitch table

• Material sales tax applied to the material fraction of each line item

• Overhead & Profit OFF by default (include_op: true to add 10/10)

MIT license.

Calibration against EagleView

tests/fetch_cache.py downloads the Solar API rasters for a set of addresses once (needs GOOGLE_MAPS_API_KEY); tests/calibrate.py then runs the engine offline and prints every measurement next to the EagleView value. Add a report's numbers to TRUTH in calibrate.py to extend the set. Synthetic roofs with analytic truth live in tests/synth.py (pytest).