MCP Tools Reference
SolarSens MCP provides powerful tools for accessing and analyzing solar plant and inverter data.
Plant-Level Tools
These tools operate at the plant portfolio level.
fetch_operation_overview
Get daily performance overview for all authorized plants.
Description
Retrieves a comprehensive daily operation overview showing performance metrics for all plants you have access to. This is the quickest way to see how your entire portfolio performed on a given day.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
date_str | string | No | Date in YYYY-MM-DD format. Defaults to yesterday if not provided. |
Returns
JSON array containing daily performance metrics for each plant:
{
"data": [
{
"plant_id": "plant_123",
"plant_name": "Ho_Chi_Minh_City_1",
"date": "2024-10-01",
"energy_kwh": 12500.5,
"performance_ratio": 0.85,
"availability": 0.98,
"capacity_kwp": 15000,
"country": "Vietnam"
}
]
}
Example Usage
User: "Show me yesterday's performance for all my plants"
Claude: I'll fetch the operation overview for yesterday...
[Calls fetch_operation_overview with date_str="2024-10-01"]
Based on yesterday's data, here's the performance summary:
- Plant 1: 12,500 kWh generated (Performance ratio: 85%)
- Plant 2: 8,750 kWh generated (Performance ratio: 82%)
...
Constraints
- Maximum date: Yesterday (cannot fetch today or future dates)
- Only returns data for plants you're authorized to access
- Data availability depends on plant reporting systems
list_plants
List all solar plants you have access to.
Description
Returns a formatted list of all authorized plants with their details including capacity, location, and plant ID. This is useful for discovering what plants are available before running analysis.
Parameters
None - automatically uses your authenticated user context.
Returns
Formatted text list of plants:
Available Plants:
1. Ho_Chi_Minh_City_1
ID: plant_123
Capacity: 15000 kWp
Country: Vietnam
2. Bangkok_Solar_2
ID: plant_456
Capacity: 20000 kWp
Country: Thailand
...
Example Usage
User: "What plants do I have access to?"
Claude: Let me check your authorized plants...
[Calls list_plants]
You have access to 5 solar plants:
1. Ho_Chi_Minh_City_1 (15,000 kWp) in Vietnam
2. Bangkok_Solar_2 (20,000 kWp) in Thailand
...
Use Cases
- Discovering available plants before analysis
- Checking plant names for historical queries
- Verifying access permissions
- Getting plant capacity information
analyze_plant_history
Analyze historical performance data for a specific plant over a date range.
Description
Fetches and analyzes historical performance data for a specific plant. Supports fuzzy matching on plant names and handles multiple date ranges. If the plant name is ambiguous, Claude will prompt you to select from matching options.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
plant_name | string | Yes | Name or partial name of the plant (e.g., "Ho_Chih_minh", "plant 1") |
start_date | string | Yes | Start date in YYYY-MM-DD format |
end_date | string | No | End date in YYYY-MM-DD format. Defaults to yesterday if not provided. |
Returns
JSON object with metadata and historical data array:
{
"metadata": {
"plant": "Ho_Chi_Minh_City_1",
"plant_id": "plant_123",
"start_date": "2024-09-01",
"end_date": "2024-09-30",
"records_count": 30
},
"data": [
{
"date": "2024-09-01",
"energy_kwh": 12500.5,
"performance_ratio": 0.85,
"availability": 0.98,
...
},
...
]
}
Example Usage
Basic Historical Analysis
User: "Analyze the last 30 days for Ho Chi Minh City plant"
Claude: I'll analyze the historical data...
[Calls analyze_plant_history with:
plant_name="Ho Chi Minh City"
start_date="2024-09-01"
end_date="2024-09-30"
]
Analysis for Ho_Chi_Minh_City_1 (Sep 1-30, 2024):
- Total energy: 375,000 kWh
- Average performance ratio: 84%
- Best day: Sep 15 (13,200 kWh)
- Worst day: Sep 22 (9,800 kWh)
Fuzzy Name Matching
User: "Show me data for 'plant 1' from last week"
Claude: I found 3 plants matching 'plant 1':
1. Ho_Chi_Minh_City_1
2. Bangkok_Plant_1
3. Singapore_Plant_1
Which one would you like to analyze?
User: "The first one"
[Calls analyze_plant_history with selected plant]
Constraints
- End date cannot be today or in the future
- Start date must be before end date
- Maximum range depends on data availability
- Plant name must match at least one authorized plant
Advanced Features
Smart Plant Selection
- Fuzzy matching: "ho chi" matches "Ho_Chi_Minh_City_1"
- Case-insensitive search
- Partial name matching
- Session memory: Selected plant is remembered for subsequent queries
Data Range Handling
- Automatic defaults: End date defaults to yesterday
- Validation: Prevents invalid date ranges
- Missing data handling: Returns available data even if some dates are missing
Inverter-Level Tools
These tools operate at the inverter level within a specific plant. All inverter tools require a plant ID parameter.
fetch_daily_operation_overview_inverters
Get daily performance overview for all inverters in a specific plant.
Description
Retrieves comprehensive daily operation overview showing performance metrics for all inverters in the specified plant. This allows you to drill down into inverter-level performance.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
plant_id | string | Yes | Plant ID to query inverters for |
date_str | string | No | Date in YYYY-MM-DD format. Defaults to yesterday if not provided. |
Returns
JSON array containing daily performance metrics for each inverter:
{
"data": [
{
"date": "2025-10-02",
"plant_id": "plant_123",
"name": "CMES-PR018-I06",
"label": "CMES-PR018-I06",
"device_id": "device_456",
"Daily Yield": 607.8,
"Total Yield": 866211.4,
"Daily Derating Loss": 0,
"Daily Operation Time": 729,
"availability_sum": 144,
"interval_count": 144,
"Total Operation Time": 20811,
"availability": 1,
"customer": "SHARED@CMES"
}
],
"row_count": 20
}
Example Usage
User: "Show me inverter performance for plant xyz123 yesterday"
Claude: I'll fetch the inverter overview for yesterday...
[Calls fetch_daily_operation_overview_inverters with plant_id="xyz123"]
Based on yesterday's data for Plant ABC:
- Inverter I06: 607.8 kWh (Availability: 100%)
- Inverter I07: 625.9 kWh (Availability: 100%)
...
Constraints
- Maximum date: Yesterday (cannot fetch today or future dates)
- Requires valid plant_id from your authorized plants
- Only returns inverters for the specified plant
list_available_inverters
List all inverters for a specific plant.
Description
Returns a formatted list of all inverters in the specified plant with their key performance metrics. Useful for discovering what inverters exist before running detailed analysis.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
plant_id | string | Yes | Plant ID to list inverters for |
date_str | string | No | Date to use for getting inverter list. Defaults to yesterday. |
Returns
Formatted text list of inverters:
Inverters for Plant ABC (Plant ID: xyz123)
Date: 2025-10-02
1. CMES-PR018-I06
Device ID: device_456
Daily Yield: 607.8 kWh
Availability: 100.0%
2. CMES-PR038-I06
Device ID: device_789
Daily Yield: 405.0 kWh
Availability: 100.0%
...
Total: 20 inverters
Example Usage
User: "List all inverters in plant xyz123"
Claude: Let me check the inverters for that plant...
[Calls list_available_inverters with plant_id="xyz123"]
Plant ABC has 20 inverters:
1. CMES-PR018-I06 (607.8 kWh, 100% availability)
2. CMES-PR038-I06 (405.0 kWh, 100% availability)
...
Use Cases
- Discovering inverters in a plant before analysis
- Checking inverter names for historical queries
- Quick availability scan across all inverters
- Identifying underperforming inverters
analyze_inverter_historical_data
Analyze historical performance data for a specific inverter over a date range.
Description
Fetches and analyzes historical performance data for a specific inverter within a plant. Supports fuzzy matching on inverter names and handles multiple date ranges. If the inverter name is ambiguous, Claude will prompt you to select from matching options.
For LLM/Claude: Inverters follow the naming pattern I01, I02, I03, etc. When the user says "inverter 1" or "inverter 01", translate it to the device label.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
plant_id | string | Yes | Plant ID where the inverter is located |
inverter_name | string | Yes | Inverter identifier. LLM should translate user queries: "inverter 1" → "CUSTOMER-PR018-I01", "inverter 6" → "CUSTOMER-PR018-I06". Also accepts partial names like "I06" or full device labels. |
start_date | string | Yes | Start date in YYYY-MM-DD format |
end_date | string | No | End date in YYYY-MM-DD format. Defaults to yesterday if not provided. |
Returns
JSON object with metadata and historical data array:
{
"metadata": {
"plant": "Plant ABC",
"plant_id": "xyz123",
"inverter": "CMES-PR018-I06",
"device_id": "device_456",
"start_date": "2025-09-01",
"end_date": "2025-09-30",
"records_count": 30
},
"data": [
{
"date": "2025-09-01",
"plant_id": "xyz123",
"name": "CMES-PR018-I06",
"label": "CMES-PR018-I06",
"device_id": "device_456",
"Daily Yield": 607.8,
"Total Yield": 866211.4,
"Daily Derating Loss": 0,
"Daily Operation Time": 729,
"availability": 1,
...
},
...
]
}
Example Usage
Basic Historical Analysis
User: "Analyze inverter 1 in plant xyz123 for the last 7 days"
Claude: I'll analyze the inverter data...
[Translates "inverter 1" → "CUSTOMER-PR018-I01", then calls analyze_inverter_historical_data with:
plant_id="xyz123"
inverter_name="CUSTOMER-PR018-I01"
start_date="2025-09-24"
end_date="2025-09-30"
]
Analysis for CUSTOMER-PR018-I01 in Plant ABC (Sep 24-30):
- Average daily yield: 595 kWh
- Availability: 100%
- Total derating loss: 15.2 kWh
- Best day: Sep 26 (625 kWh)
Fuzzy Name Matching
User: "Analyze inverter containing 'I06' in plant xyz123"
Claude: I found 3 inverters matching 'I06':
1. CMES-PR018-I06
2. CMES-PR038-I06
3. CMES-PR076-I06
Which one would you like to analyze?
[Prompts for selection and continues with analysis]
Constraints
- End date cannot be today or in the future
- Start date must be before end date
- Inverter must exist in the specified plant
- Plant ID must be in your authorized plants
Advanced Features
Smart Inverter Selection
- Fuzzy matching: "I06" matches "CMES-PR018-I06"
- Case-insensitive search
- Partial name matching
- Multiple match handling with elicitation
Data Range Handling
- Automatic defaults: End date defaults to yesterday
- Validation: Prevents invalid date ranges
- Missing data handling: Returns available data even if some dates are missing
Common Patterns
Daily Monitoring Workflow
1. "List all plants I have access to"
→ Get overview of portfolio
2. "Show me yesterday's performance"
→ Quick check on all plants
3. "Analyze the last 7 days for [specific plant]"
→ Deep dive into underperforming plants
Monthly Reporting
1. "Show me September performance for all plants"
→ Get monthly overview
2. "Analyze Plant X from September 1-30"
→ Detailed monthly analysis per plant
3. "Compare performance ratios across all plants"
→ Portfolio-wide insights
Troubleshooting Issues
1. "Which plants had availability below 95% yesterday?"
→ Identify problem plants
2. "Analyze the last 30 days for [problem plant]"
→ Check if issue is recurring
3. "Show me the trend for [specific metric]"
→ Deep dive into specific issues
Inverter-Level Troubleshooting
1. "List inverters for plant xyz123"
→ Get overview of all inverters
2. "Show inverter performance for plant xyz123 yesterday"
→ Identify underperforming inverters
3. "Analyze inverter I06 in plant xyz123 for the last 7 days"
→ Deep dive into specific inverter issues
4. "Which inverters have high derating losses in plant xyz123?"
→ Investigate efficiency issues
Error Handling
All tools handle errors gracefully:
- Invalid dates: Returns error message with valid format
- No access: Returns message if you don't have access to requested plant
- No data: Returns helpful message if data is unavailable
- Network issues: Retries automatically with caching