[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

# Solar MCP

A community-sponsored open-source [MCP](https://modelcontextprotocol.io/) server that wraps solar industry APIs as tools for AI assistants. Built with [FastMCP](https://github.com/jlowin/fastmcp) and hosted as a public endpoint at `api.ontologic.co/solar-mcp`.

Solar MCP gives AI assistants the ability to look up permitting authorities, estimate solar production, and retrieve solar resource data — making it easy to build solar-aware AI workflows.

---

## Available Tools

### `lookup_ahj`

Look up the Authority Having Jurisdiction (AHJ) for a solar installation site.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `address` | string | One of address or lat/lon | Street address |
| `lat` | float | One of address or lat/lon | Latitude |
| `lon` | float | One of address or lat/lon | Longitude |

**Returns:** `ahj_name`, `ahj_id`, `building_code`, `electrical_code`, `fire_code`, `permit_authority`, `inspection_body`, `contact_name`, `contact_email`, `contact_phone`, `website`

### `lookup_ahj_requirements`

Look up detailed permitting requirements for a specific AHJ.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ahj_id` | string | Yes | AHJ ID from `lookup_ahj` |

**Returns:** `nec_version`, `ibc_version`, `irc_version`, `special_requirements` (list), `permit_process_notes`, `online_submission` (bool), `typical_turnaround_days`

### `lookup_pvwatts`

Get a PVWatts v8 solar production estimate.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `address` | string | One of address or lat/lon | — | Street address |
| `lat` | float | One of address or lat/lon | — | Latitude |
| `lon` | float | One of address or lat/lon | — | Longitude |
| `system_capacity_kw` | float | Yes | — | System size in kW |
| `tilt` | float | No | 20 | Panel tilt angle |
| `azimuth` | float | No | 180 | Panel azimuth (180 = south) |
| `array_type` | int | No | 1 | 0=fixed ground, 1=fixed open rack, 2=1-axis, 3=1-axis backtrack, 4=2-axis |
| `module_type` | int | No | 0 | 0=standard, 1=premium, 2=thin film |
| `losses` | float | No | 14 | System losses (%) |

**Returns:** `ac_annual_kwh`, `ac_monthly_kwh` (12 values), `solrad_annual`, `capacity_factor`, `station_info`

### `lookup_solar_resource`

Get solar resource data (irradiance) for a location.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `address` | string | One of address or lat/lon | Street address |
| `lat` | float | One of address or lat/lon | Latitude |
| `lon` | float | One of address or lat/lon | Longitude |

**Returns:** `avg_dni`, `avg_ghi`, `avg_lat_tilt`, `nearest_station_name`, `station_distance_miles`

---

## Connect in Claude Desktop

Add this to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "solar-mcp": {
      "url": "https://api.ontologic.co/solar-mcp/mcp"
    }
  }
}
```

Or to run locally:

```json
{
  "mcpServers": {
    "solar-mcp": {
      "url": "http://localhost:8000/solar-mcp/mcp"
    }
  }
}
```

---

## Run Locally

### With Docker

```bash
docker build -t solar-mcp .
docker run -p 8000:8000 \
  -e NREL_API_KEY=your_key_here \
  -e SUNSPEC_API_TOKEN=your_token_here \
  solar-mcp
```

### Without Docker

```bash
pip install -e ".[dev]"
cp .env.example .env
# Edit .env with your API keys
python server.py
```

---

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `NREL_API_KEY` | Yes | NREL API key ([get one free](https://developer.nrel.gov/signup/)) |
| `SUNSPEC_API_TOKEN` | No | SunSpec AHJ Registry token (mock data used until available) |
| `PORT` | No | Server port (default: 8000) |

---

## Running Tests

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

---

## Attribution

- **[NREL](https://www.nrel.gov/)** — PVWatts v8 API and Solar Resource Data API. This tool uses the NREL Developer Network API but is not endorsed or certified by NREL.
- **[SunSpec Alliance](https://sunspec.org/)** — AHJ Registry API. AHJ data is currently mocked based on publicly available information; real API integration is pending token access.

---

## Contributing

Contributions are welcome! To add a new tool:

1. Add Pydantic schemas in `models/schemas.py`
2. Add a client in `clients/` (keep API interaction separate from tool logic)
3. Add the tool function in `tools/`
4. Register the tool in `server.py`
5. Add tests in `tests/`
6. Update this README

Please open an issue first to discuss new tools or significant changes.

---

## License

MIT