Metadata-Version: 2.4
Name: eg4-mcp-server
Version: 0.1.2
Summary: Model Context Protocol server for EG4 solar inverter monitoring and control
Project-URL: Homepage, https://github.com/matt-dreyer/EG4_MCP_server
Project-URL: Repository, https://github.com/matt-dreyer/EG4_MCP_server
Project-URL: Documentation, https://github.com/matt-dreyer/EG4_MCP_server#readme
Project-URL: Issues, https://github.com/matt-dreyer/EG4_MCP_server/issues
Project-URL: Discussions, https://github.com/matt-dreyer/EG4_MCP_server/discussions
Project-URL: Changelog, https://github.com/matt-dreyer/EG4_MCP_server/blob/main/CHANGELOG.md
Author-email: Matt Dreyer <matt_dreyer@hotmail.com>
Maintainer-email: Matt Dreyer <matt_dreyer@hotmail.com>
License: MIT License
        
        Copyright (c) 2025 EG4 MCP Server Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE.md
Keywords: battery,eg4,energy,home-automation,inverter,mcp,monitoring,photovoltaic,renewable,solar
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Home Automation
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.8.5
Requires-Dist: eg4-python
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp[cli]>=1.11.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=8.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser>=2.0.0; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == 'docs'
Requires-Dist: sphinx>=6.0.0; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=1.0.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
Requires-Dist: pytest>=8.4.0; extra == 'test'
Description-Content-Type: text/markdown

# 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)

```bash
# 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:
```bash
git clone https://github.com/yourusername/eg4-mcp-server.git
cd eg4-mcp-server
```

2. Install dependencies:
```bash
pip install -e .
```

## Configuration

1. Copy the environment template:
```bash
cp .env.example .env
```

2. Edit `.env` with your EG4 credentials:
```env
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:
```bash
python server.py
```

Or use the MCP CLI:
```bash
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`:

```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:
```json
{
  "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](CONTRIBUTING.md) for details.

### Development Setup

1. Fork the repository
2. Create a virtual environment:
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```
3. Install development dependencies:
   ```bash
   pip install -e ".[dev]"
   ```
4. Make your changes and run tests:
   ```bash
   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:
```bash
export EG4_DEBUG=1
python server.py
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Inspired by the [eg4_inverter_api](https://github.com/twistedroutes/eg4_inverter_api) library
- Powered by the [Model Context Protocol](https://modelcontextprotocol.io/)
- Special thanks to the EG4 community for reverse-engineering efforts

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and changes.

## Support

- 📖 **Documentation**: Check this README and inline tool documentation
- 🐛 **Bug Reports**: [Open an issue](https://github.com/yourusername/eg4-mcp-server/issues)
- 💡 **Feature Requests**: [Open an issue](https://github.com/yourusername/eg4-mcp-server/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/yourusername/eg4-mcp-server/discussions)

---

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