eg4-mcp-server 0.1.5

Model Context Protocol server for EG4 solar inverter monitoring and control

EG4 MCP Server

An MCP (Model Context Protocol) Server for the EG4 Solar Inverter Monitoring API, providing comprehensive solar system monitoring and analysis capabilities.

Features

• 🔌 Real-time monitoring - Current production, consumption, and system status
• 📊 Performance analysis - Efficiency metrics and grid independence calculations
• 🔋 Battery health monitoring - SOH, SOC, and cycle count tracking
• ⚠️ Smart alerts - Proactive issue detection and notifications
• 🛠️ Maintenance insights - Automated recommendations and scheduling
• 📈 Historical data - Energy production and consumption trends
• 🏥 System health scoring - Component-level health assessment

Installation

Quick start (dev mode)

# 1. create & activate venv
cd eg4_mcp_server
python -m venv .venv
.venv\Scripts\activate   # PowerShell: .venv\Scripts\Activate.ps1

# 2. install requirements
pip install -r requirements.txt

# 3. run the server
python server.py

### Prerequisites

- Python 3.10 or higher
- EG4 inverter with online monitoring account
- Access to EG4 monitoring portal credentials

### Install from PyPI
```bash
pip install eg4-mcp-server

Install from Source

1. Clone the repository:

git clone https://github.com/yourusername/eg4-mcp-server.git
cd eg4-mcp-server

2. Install dependencies:

pip install -e .

Configuration

1. Copy the environment template:

cp .env.example .env

2. Edit .env with your EG4 credentials:

EG4_USERNAME=your_eg4_username
EG4_PASSWORD=your_eg4_password
EG4_BASE_URL=https://monitor.eg4electronics.com
EG4_DISABLE_VERIFY_SSL=0

Usage

Running the MCP Server

Start the server directly:

python server.py

Or use the MCP CLI:

mcp run server.py

Available Tools

Tool	Description
Fetch_Configuration	Get complete system configuration and status
Get_System_Details	Detailed system information and inverter specs
Get_Current_Production	Real-time production and consumption data
Get_Performance_Analysis	Performance metrics and efficiency analysis
Get_Historical_Data	Historical energy data and trends
Get_System_Alerts	System health alerts and warnings
Get_System_Health	Comprehensive health scoring
Get_Maintenance_Insights	Maintenance recommendations and scheduling

Example Usage with Claude

1. Check current system status:

   What's my solar system producing right now?
   

2. Get performance analysis:

   How is my solar system performing this week?
   

3. Check for alerts:

   Are there any issues with my solar system?
   

4. Get maintenance recommendations:

   What maintenance does my solar system need?
   

Integration with AI Assistants

This MCP server is designed to work with AI assistants that support the Model Context Protocol, such as:

• Claude Desktop - Add to your MCP configuration
• Other MCP-compatible clients

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "eg4": {
      "command": "python",
      "args": ["-m", "eg4_mcp_server"],
      "env": {
        "EG4_USERNAME": "your_username",
        "EG4_PASSWORD": "your_password"
      }
    }
  }
}

API Reference

Tool Parameters

Most tools accept optional parameters:

• system_id (int, optional): Specific system ID (defaults to first system)
• days_back (int): Number of days for historical data (default varies by tool)
• threshold_percent (float): Performance threshold for maintenance insights

Response Format

All tools return JSON responses with:

• timestamp: ISO format timestamp
• data: Tool-specific data structure
• error: Error message if applicable

Example response:

{
  "timestamp": "2025-06-24T10:30:00",
  "system_status": "Normal",
  "current_production": {
    "solar_power": "2.5 kW",
    "battery_discharge": "0.0 W",
    "home_consumption": "1.8 kW"
  }
}

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

1. Fork the repository
2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install development dependencies:

   pip install -e ".[dev]"
   

4. Make your changes and run tests:

   pytest
   

Troubleshooting

Common Issues

1. Authentication Failed

   • Verify your EG4 credentials in .env
   • Check if your account has API access

2. SSL Certificate Errors

   • Set EG4_DISABLE_VERIFY_SSL=1 in your .env file
   • This disables SSL verification (use with caution)

3. No Inverters Found

   • Ensure your account has associated inverters
   • Check if inverters are online in the EG4 portal

4. Connection Timeouts

   • Check your internet connection
   • Verify the EG4_BASE_URL is correct

Debug Mode

Enable verbose logging by setting the environment variable:

export EG4_DEBUG=1
python server.py

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by the eg4_inverter_api library
• Powered by the Model Context Protocol
• Special thanks to the EG4 community for reverse-engineering efforts

Changelog

See CHANGELOG.md for version history and changes.

Support

• 📖 Documentation: Check this README and inline tool documentation
• 🐛 Bug Reports: Open an issue
• 💡 Feature Requests: Open an issue
• 💬 Discussions: GitHub Discussions

---

Note: This project is not officially affiliated with EG4 Electronics. It's a community-driven project for interfacing with EG4 monitoring systems.