Submit
cwoodcox

pvwatts-mcp

Community cwoodcox
Updated

MCP server wrapping NREL PVWatts v8.

pvwatts-mcp

MCP server wrapping NREL PVWatts v8 for the Watts for Water project. Turns a parcel centroid + acreage into annual / monthly generation estimates suitable for revenue modeling and infographic headline numbers.

See spec.md for the design doc.

Tools

Tool Purpose
pvwatts_run Faithful wrapper around PVWatts v8. All parameters exposed; project defaults applied when omitted.
solar_potential_for_acres Convenience: acreage + centroid → MW DC → annual MWh, capacity factor, indicative revenue. tracker=true flips to 1-axis backtracking.

Setup

npm install

Get a free NREL API key at developer.nrel.gov/signup, then store it as a Worker secret:

npx wrangler secret put NREL_API_KEY

For local development with wrangler dev, put the same key in a .dev.vars file at the repo root (gitignored):

NREL_API_KEY=your-key-here

Running locally

npm run dev

Worker listens at http://localhost:8787. Test endpoints:

  • GET / — plain-text usage hint
  • POST /mcp — streamable HTTP transport (recommended)
  • GET /sse — legacy SSE transport

Inspect with the MCP Inspector:

npx @modelcontextprotocol/inspector@latest
# Then open the URL it prints and connect to http://localhost:8787/mcp

Deploying

npx wrangler deploy

Then connect from Claude Desktop via mcp-remote:

{
  "mcpServers": {
    "pvwatts": {
      "command": "npx",
      "args": ["mcp-remote", "https://pvwatts-mcp.<your-account>.workers.dev/mcp"]
    }
  }
}

Acceptance test

The MCP is ready to ship when this call returns sane numbers:

// Tool: solar_potential_for_acres
{
  "lat": 41.72,
  "lon": -111.83,    // Cache Valley, Utah
  "acres": 80,
  "tracker": false
}

Expected (per spec.md § Acceptance test, within ~10%):

  • system_capacity_mw_dc: 10.0
  • annual.generation_mwh: 21,000 – 24,000
  • annual.capacity_factor_pct: 24 – 26
  • annual.indicative_revenue_usd: ~$735K – $840K at $35/MWh
  • Monthly trough in Dec/Jan (~1,000 MWh), peak in Jun/Jul (~2,400 MWh)

Re-running with tracker=true should bump annual generation to 25,000–28,000 MWh and capacity factor to ~28–30%, validating the array-type plumbing.

Layout

src/
  index.ts      Worker entrypoint — routes /mcp and /sse
  mcp.ts        McpAgent subclass; tool registrations
  pvwatts.ts    NREL adapter — fetch, retry, cache, error mapping
  defaults.ts   Utah utility-scale assumption set + caveat strings

MCP Server · Populars

MCP Server · New