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

Related MCP server: homelab-mcp

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

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.