# PG&E Data Portals MCP

> PG&E Data Portals connects your AI client directly to PG&E's public energy datasets. Query electricity usage, solar generation capacity, and EV adoption trends by ZIP code and date range. Use this server to programmatically analyze grid infrastructure data for planning, research, or market analysis.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** energy-usage, ev-adoption, grid-data, public-datasets, data-query

## Description

Listen up. This server hooks your agent right into PG&E’s public energy data portals. It's not some slick, vague dashboard; it gives you programmatic access to actual usage patterns, solar capacity figures, and grid infrastructure details. You don't gotta mess with manual downloads or weird web forms—your AI client just uses structured tools to get exactly what you need.

**Finding Your Data**

If you're not sure where the info lives, start by listing everything available using `list_all_datasets`; this shows every dataset PG&E tracks, from usage numbers to EV adoption rates. You can refine that search with `search_datasets` if you know a keyword but don't know the ID. Before running any query, you gotta check the structure; use `get_dataset_schema` by plugging in a specific PG&E dataset ID. This tells you all the column names and data types, so you never waste time on a bad query.

**Pulling General Data & Trends**

You can pull records from any dataset that fall between two dates using `query_by_date_range` for trend analysis. For general querying when you know what you're looking for, run `query_dataset`, letting the tool filter by key-value pairs like a specific ZIP code or region.

**Analyzing Energy Use and Efficiency**

To check electricity or gas consumption data, use `query_energy_usage`. You can get records broken down specifically by customer segment—say, residential—and filtered precisely by ZIP code. If you're tracking energy efficiency programs, `query_energy_efficiency` gets you the program results and estimated savings amounts, letting you narrow it down by year or specific program type.

**Tracking Renewables and Grid Health**

For solar power, `query_solar_generation` collects statistics on production—like installed capacity or net energy metering—for a defined county or service area in a given year. If you need to assess the physical grid, `query_grid_infrastructure` pulls data on distribution circuits, substations, and overall grid capacity metrics, letting you filter by region or infrastructure type. These tools let you map out where the power actually runs.

**Mobility and Consumption Analysis**

Need to track electric vehicles? `query_ev_adoption` retrieves EV registration counts, showing adoption rates for specific ZIP codes across years. For a comprehensive view of consumption, you can use `query_energy_usage` or look at solar metrics with `query_solar_generation`. These tools let you programmatically analyze everything from how many cars are electric to how much power the grid actually supports.

It's built for the guy who needs reliable, structured access to time-series energy data. You don't waste time on guesswork; your agent just pulls the numbers straight out.

## Tools

### query_by_date_range
Retrieves records from any dataset that fall within specified start and end dates for trend analysis.

### query_ev_adoption
Retrieves electric vehicle registration counts, showing adoption rates for specific ZIP codes and years.

### query_energy_efficiency
Gets program results and savings amounts for energy efficiency initiatives, filtered by year and program type.

### query_energy_usage
Queries electricity or gas consumption data broken down by customer segment (e.g., residential) and ZIP code.

### get_dataset_schema
Shows the column names and data types for a specific PG&E dataset ID.

### query_grid_infrastructure
Queries data on distribution circuits, substations, and grid capacity by region or infrastructure type.

### list_all_datasets
Returns a list of all available datasets, including energy usage, solar, EV adoption, and grid infrastructure.

### query_dataset
Queries a specific PG&E dataset using key-value filters like zip code or region to get data records.

### search_datasets
Searches the PG&E catalog using keywords to discover relevant datasets before running a full query.

### query_solar_generation
Gathers solar energy production statistics (capacity/production) for a specific county or service area in a given year.

## Prompt Examples

**Prompt:** 
```
List all available PG&E datasets.
```

**Response:** 
```
Found datasets including: Energy Usage by ZIP Code (monthly electricity and gas consumption by customer segment), EV Adoption (electric vehicle registrations by ZIP code), Solar Generation (installed capacity and production), Energy Efficiency Programs (participation and savings), and Grid Infrastructure (distribution circuits and substations). Which dataset would you like to explore?
```

**Prompt:** 
```
Show me electricity usage for ZIP code 94102.
```

**Response:** 
```
Electricity usage for 94102 (San Francisco - Mission District): Jan 2024: 2,450,000 kWh (Residential), 3,120,000 kWh (Commercial). Feb 2024: 2,280,000 kWh (Residential), 2,980,000 kWh (Commercial). Average residential bill: $142/month. Peak usage in January during winter heating season.
```

**Prompt:** 
```
Show EV adoption trends by ZIP code for 2024.
```

**Response:** 
```
EV adoption data for 2024: 94301 (Palo Alto): 12,450 EVs registered (38% of households). 94102 (SF Mission): 3,280 EVs (15%). 94040 (Mountain View): 9,870 EVs (32%). 95054 (Santa Clara): 7,650 EVs (28%). Highest adoption in Peninsula/Silicon Valley ZIP codes with proximity to tech employers and charging infrastructure.
```

## Capabilities

### Catalog all available datasets
Lists every dataset PG&E tracks—including usage, solar, and grid data—so you know exactly where to look.

### Inspect dataset structure
Retrieves the schema (columns and data types) for any specific PG&E dataset ID before running a query.

### Query consumption by location and time
Gets electricity or gas usage records, filtered precisely by ZIP code and date range.

### Analyze EV adoption trends
Retrieves electric vehicle registration counts and adoption rates for specific ZIP codes and years.

### Assess grid infrastructure capacity
Accesses distribution circuit, substation data, and general grid capacity metrics by region.

### Track solar energy production
Gathers solar generation statistics (like installed capacity or net energy metering) for a specific county or service area.

## Use Cases

### Assessing new development viability
A developer needs to know if a proposed commercial building in ZIP code 94102 can be supported by the existing grid. They use `list_all_datasets` to find 'Grid Infrastructure,' then run `query_grid_infrastructure` filtered by that ZIP code and check capacity metrics. The agent returns data showing the current substation load, flagging if the site requires an immediate upgrade.

### Modeling clean energy market potential
A clean tech company wants to find the best area for a solar farm. They use `query_solar_generation` filtered by county name and year to see current capacity vs. land availability. They then cross-reference this with `query_ev_adoption` data to confirm high population density, pinpointing maximum return zones.

### Analyzing historical consumption changes
A researcher wants to track how residential gas usage in a specific area changed following an economic downturn. They use `list_all_datasets`, locate the energy usage dataset, and run `query_by_date_range` with start and end dates covering the relevant period for precise trend analysis.

### Comparing different segments' needs
An energy consultant must compare commercial versus residential electricity load. They use `list_all_datasets`, then run `query_energy_usage`. By specifying 'Commercial' and 'Residential' as customer segments, they get side-by-side data for the same ZIP code over a set time frame.

## Benefits

- See precise regional usage data using `query_energy_usage`. You get electricity and gas consumption broken down by customer segment (residential, commercial) for any ZIP code you specify. This is critical for understanding localized demand spikes.
- Understand infrastructure limits with `query_grid_infrastructure`. The server provides capacity metrics on distribution circuits and substations, helping planners identify exactly where an upgrade or expansion is needed before a project starts.
- Model future growth rates using `query_ev_adoption`. You can track how many EVs are registered across different ZIP codes year over year. This directly informs planning for necessary charging infrastructure build-outs.
- Measure program effectiveness by running `query_energy_efficiency`. Instead of guessing, you get hard data on energy savings achieved and participation rates, letting you calculate true return on investment (ROI).
- Discover the full scope of available information with `list_all_datasets`. This function acts like a master index, showing every dataset PG&E tracks—from basic usage to complex solar capacity figures.
- Filter data accurately using date range queries. The `query_by_date_range` tool lets you compare consumption trends year-over-year or quarter-to-quarter without manual spreadsheet manipulation.

## How It Works

The bottom line is: it lets you build complex energy reports using simple chat prompts instead of manual API calls or spreadsheet merging.

1. First, use `list_all_datasets` to see the full catalog of available PG&E data.
2. Next, run `get_dataset_schema` on a promising dataset ID. This lets you confirm the exact field names and acceptable values (e.g., 'ZIP code' or 'Region').
3. Finally, execute a specific tool like `query_energy_usage`, passing the required parameters (ID, ZIP code, dates) to get clean data records.

## Frequently Asked Questions

**How do I find all available PG&E datasets using list_all_datasets?**
Run `list_all_datasets`. This returns a catalog of every dataset, including energy usage, EV adoption, and grid infrastructure. It’s the best place to start when you don't know which data set you need.

**What is the difference between query_dataset and get_dataset_schema?**
`list_all_datasets` gives you a list of available topics. `get_dataset_schema` drills down to show the column names, data types, and constraints for one specific dataset ID, letting you know exactly what fields you can filter on.

**How do I query EV adoption rates by ZIP code?**
Use `query_ev_adoption`. You need to provide the 5-digit ZIP code and the specific year (YYYY format) in your prompt. This tool is designed specifically for this data type.

**Can I analyze solar generation capacity trends using query_solar_generation?**
Yes, `query_solar_generation` handles that. You must specify the region (county name or service area) and the year to retrieve production statistics for trend analysis.

**What filters can I use with query_energy_usage?**
`query_energy_usage` requires you to specify the ZIP code and a date range. You also select the customer segment (residential, commercial, industrial) you want to analyze.

**What happens to my queries using `query_dataset` if I hit rate limits?**
You need an API key for high volume analysis. For sustained data querying, provide your PG&E Data Portals API Key during setup. This increases your allowed calls and keeps your complex analyses running without interruption.

**What format must I use when calling `query_by_date_range`?**
The system requires the YYYY-MM-DD standard date format. Always pass both start and end dates using this structure to guarantee accurate filtering for any time-series comparison.

**How do I narrow down my search results before running `query_dataset`?**
Use the keyword parameter when calling `search_datasets`. This filters the entire catalog based on your input, helping you find the exact dataset ID needed before you attempt to retrieve any data records.

**What types of datasets are available?**
PG&E Data Portals offers: energy usage (electricity and gas by ZIP code), EV adoption (vehicle registrations), solar generation (capacity and production), energy efficiency programs (participation and savings), and grid infrastructure (distribution circuits, substations). Use search_datasets to discover all available datasets.

**Is authentication required?**
No, the PG&E Data Portals API is publicly accessible without authentication. An API key is optional and only needed if you want higher rate limits for production use. Most queries work out of the box without any credentials.

**Can I filter data by specific ZIP codes and date ranges?**
Yes! Most tools support zip_code, start_date, and end_date parameters. For example, query_energy_usage accepts ZIP code and date range to return electricity consumption for that specific area and period. Use query_by_date_range for any dataset with custom date filtering.