eg4-mcp-server


Nameeg4-mcp-server JSON
Version 0.1.5 PyPI version JSON
download
home_pageNone
SummaryModel Context Protocol server for EG4 solar inverter monitoring and control
upload_time2025-07-16 02:05:11
maintainerNone
docs_urlNone
authorNone
requires_python>=3.10
licenseMIT 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.
keywords battery eg4 energy home-automation inverter mcp monitoring photovoltaic renewable solar
VCS
bugtrack_url
requirements aiohttp python-dotenv mcp httpx eg4_python pytest pytest-asyncio
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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.
            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "eg4-mcp-server",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": "Matt Dreyer <matt_dreyer@hotmail.com>",
    "keywords": "battery, eg4, energy, home-automation, inverter, mcp, monitoring, photovoltaic, renewable, solar",
    "author": null,
    "author_email": "Matt Dreyer <matt_dreyer@hotmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/81/c9/48807203e4e22fca322fde79dfe1e0e55750e5a54ee4c9d16994cafadde8/eg4_mcp_server-0.1.5.tar.gz",
    "platform": null,
    "description": "# EG4 MCP Server\n\nAn MCP (Model Context Protocol) Server for the EG4 Solar Inverter Monitoring API, providing comprehensive solar system monitoring and analysis capabilities.\n\n## Features\n\n- \ud83d\udd0c **Real-time monitoring** - Current production, consumption, and system status\n- \ud83d\udcca **Performance analysis** - Efficiency metrics and grid independence calculations\n- \ud83d\udd0b **Battery health monitoring** - SOH, SOC, and cycle count tracking\n- \u26a0\ufe0f **Smart alerts** - Proactive issue detection and notifications\n- \ud83d\udee0\ufe0f **Maintenance insights** - Automated recommendations and scheduling\n- \ud83d\udcc8 **Historical data** - Energy production and consumption trends\n- \ud83c\udfe5 **System health scoring** - Component-level health assessment\n\n## Installation\n\n### Quick start (dev mode)\n\n```bash\n# 1. create & activate venv\ncd eg4_mcp_server\npython -m venv .venv\n.venv\\Scripts\\activate   # PowerShell: .venv\\Scripts\\Activate.ps1\n\n# 2. install requirements\npip install -r requirements.txt\n\n# 3. run the server\npython server.py\n\n### Prerequisites\n\n- Python 3.10 or higher\n- EG4 inverter with online monitoring account\n- Access to EG4 monitoring portal credentials\n\n### Install from PyPI\n```bash\npip install eg4-mcp-server\n```\n\n### Install from Source\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/yourusername/eg4-mcp-server.git\ncd eg4-mcp-server\n```\n\n2. Install dependencies:\n```bash\npip install -e .\n```\n\n## Configuration\n\n1. Copy the environment template:\n```bash\ncp .env.example .env\n```\n\n2. Edit `.env` with your EG4 credentials:\n```env\nEG4_USERNAME=your_eg4_username\nEG4_PASSWORD=your_eg4_password\nEG4_BASE_URL=https://monitor.eg4electronics.com\nEG4_DISABLE_VERIFY_SSL=0\n```\n\n## Usage\n\n### Running the MCP Server\n\nStart the server directly:\n```bash\npython server.py\n```\n\nOr use the MCP CLI:\n```bash\nmcp run server.py\n```\n\n### Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `Fetch_Configuration` | Get complete system configuration and status |\n| `Get_System_Details` | Detailed system information and inverter specs |\n| `Get_Current_Production` | Real-time production and consumption data |\n| `Get_Performance_Analysis` | Performance metrics and efficiency analysis |\n| `Get_Historical_Data` | Historical energy data and trends |\n| `Get_System_Alerts` | System health alerts and warnings |\n| `Get_System_Health` | Comprehensive health scoring |\n| `Get_Maintenance_Insights` | Maintenance recommendations and scheduling |\n\n### Example Usage with Claude\n\n1. **Check current system status:**\n   ```\n   What's my solar system producing right now?\n   ```\n\n2. **Get performance analysis:**\n   ```\n   How is my solar system performing this week?\n   ```\n\n3. **Check for alerts:**\n   ```\n   Are there any issues with my solar system?\n   ```\n\n4. **Get maintenance recommendations:**\n   ```\n   What maintenance does my solar system need?\n   ```\n\n## Integration with AI Assistants\n\nThis MCP server is designed to work with AI assistants that support the Model Context Protocol, such as:\n\n- **Claude Desktop** - Add to your MCP configuration\n- **Other MCP-compatible clients**\n\n### Claude Desktop Configuration\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"eg4\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"eg4_mcp_server\"],\n      \"env\": {\n        \"EG4_USERNAME\": \"your_username\",\n        \"EG4_PASSWORD\": \"your_password\"\n      }\n    }\n  }\n}\n```\n\n## API Reference\n\n### Tool Parameters\n\nMost tools accept optional parameters:\n\n- `system_id` (int, optional): Specific system ID (defaults to first system)\n- `days_back` (int): Number of days for historical data (default varies by tool)\n- `threshold_percent` (float): Performance threshold for maintenance insights\n\n### Response Format\n\nAll tools return JSON responses with:\n- `timestamp`: ISO format timestamp\n- `data`: Tool-specific data structure\n- `error`: Error message if applicable\n\nExample response:\n```json\n{\n  \"timestamp\": \"2025-06-24T10:30:00\",\n  \"system_status\": \"Normal\",\n  \"current_production\": {\n    \"solar_power\": \"2.5 kW\",\n    \"battery_discharge\": \"0.0 W\",\n    \"home_consumption\": \"1.8 kW\"\n  }\n}\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n1. Fork the repository\n2. Create a virtual environment:\n   ```bash\n   python -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   ```\n3. Install development dependencies:\n   ```bash\n   pip install -e \".[dev]\"\n   ```\n4. Make your changes and run tests:\n   ```bash\n   pytest\n   ```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Authentication Failed**\n   - Verify your EG4 credentials in `.env`\n   - Check if your account has API access\n\n2. **SSL Certificate Errors**\n   - Set `EG4_DISABLE_VERIFY_SSL=1` in your `.env` file\n   - This disables SSL verification (use with caution)\n\n3. **No Inverters Found**\n   - Ensure your account has associated inverters\n   - Check if inverters are online in the EG4 portal\n\n4. **Connection Timeouts**\n   - Check your internet connection\n   - Verify the `EG4_BASE_URL` is correct\n\n### Debug Mode\n\nEnable verbose logging by setting the environment variable:\n```bash\nexport EG4_DEBUG=1\npython server.py\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Inspired by the [eg4_inverter_api](https://github.com/twistedroutes/eg4_inverter_api) library\n- Powered by the [Model Context Protocol](https://modelcontextprotocol.io/)\n- Special thanks to the EG4 community for reverse-engineering efforts\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history and changes.\n\n## Support\n\n- \ud83d\udcd6 **Documentation**: Check this README and inline tool documentation\n- \ud83d\udc1b **Bug Reports**: [Open an issue](https://github.com/yourusername/eg4-mcp-server/issues)\n- \ud83d\udca1 **Feature Requests**: [Open an issue](https://github.com/yourusername/eg4-mcp-server/issues)\n- \ud83d\udcac **Discussions**: [GitHub Discussions](https://github.com/yourusername/eg4-mcp-server/discussions)\n\n---\n\n**Note**: This project is not officially affiliated with EG4 Electronics. It's a community-driven project for interfacing with EG4 monitoring systems.",
    "bugtrack_url": null,
    "license": "MIT License\n        \n        Copyright (c) 2025 EG4 MCP Server Contributors\n        \n        Permission is hereby granted, free of charge, to any person obtaining a copy\n        of this software and associated documentation files (the \"Software\"), to deal\n        in the Software without restriction, including without limitation the rights\n        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n        copies of the Software, and to permit persons to whom the Software is\n        furnished to do so, subject to the following conditions:\n        \n        The above copyright notice and this permission notice shall be included in all\n        copies or substantial portions of the Software.\n        \n        THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n        SOFTWARE.",
    "summary": "Model Context Protocol server for EG4 solar inverter monitoring and control",
    "version": "0.1.5",
    "project_urls": {
        "Changelog": "https://github.com/matt-dreyer/EG4_MCP_server/blob/main/CHANGELOG.md",
        "Discussions": "https://github.com/matt-dreyer/EG4_MCP_server/discussions",
        "Documentation": "https://github.com/matt-dreyer/EG4_MCP_server#readme",
        "Homepage": "https://github.com/matt-dreyer/EG4_MCP_server",
        "Issues": "https://github.com/matt-dreyer/EG4_MCP_server/issues",
        "Repository": "https://github.com/matt-dreyer/EG4_MCP_server"
    },
    "split_keywords": [
        "battery",
        " eg4",
        " energy",
        " home-automation",
        " inverter",
        " mcp",
        " monitoring",
        " photovoltaic",
        " renewable",
        " solar"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "53fcf855026d3625d396c1c39df373363c18d2086bb3f5b6bdb9050701786283",
                "md5": "cf66b3e9cdc4beefe2655bd8a35c5bca",
                "sha256": "0bb4d561a3f6c4b2a5049fdebce0a22238cf0ae50b52c2be5409b596b1f8863f"
            },
            "downloads": -1,
            "filename": "eg4_mcp_server-0.1.5-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "cf66b3e9cdc4beefe2655bd8a35c5bca",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 15758,
            "upload_time": "2025-07-16T02:05:10",
            "upload_time_iso_8601": "2025-07-16T02:05:10.058387Z",
            "url": "https://files.pythonhosted.org/packages/53/fc/f855026d3625d396c1c39df373363c18d2086bb3f5b6bdb9050701786283/eg4_mcp_server-0.1.5-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "81c948807203e4e22fca322fde79dfe1e0e55750e5a54ee4c9d16994cafadde8",
                "md5": "cb6ed4eee3b39f38e1c954b5d2a3ae86",
                "sha256": "09fd2ee81a78670c0bc36b4e9b2624d9b1db5801cc887f7b47d9b618371f45d5"
            },
            "downloads": -1,
            "filename": "eg4_mcp_server-0.1.5.tar.gz",
            "has_sig": false,
            "md5_digest": "cb6ed4eee3b39f38e1c954b5d2a3ae86",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 15749,
            "upload_time": "2025-07-16T02:05:11",
            "upload_time_iso_8601": "2025-07-16T02:05:11.279252Z",
            "url": "https://files.pythonhosted.org/packages/81/c9/48807203e4e22fca322fde79dfe1e0e55750e5a54ee4c9d16994cafadde8/eg4_mcp_server-0.1.5.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-16 02:05:11",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "matt-dreyer",
    "github_project": "EG4_MCP_server",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "requirements": [
        {
            "name": "aiohttp",
            "specs": [
                [
                    ">=",
                    "3.8.5"
                ]
            ]
        },
        {
            "name": "python-dotenv",
            "specs": [
                [
                    ">=",
                    "1.0.0"
                ]
            ]
        },
        {
            "name": "mcp",
            "specs": [
                [
                    ">=",
                    "1.11.0"
                ]
            ]
        },
        {
            "name": "httpx",
            "specs": [
                [
                    ">=",
                    "0.28.1"
                ]
            ]
        },
        {
            "name": "eg4_python",
            "specs": []
        },
        {
            "name": "pytest",
            "specs": [
                [
                    ">=",
                    "8.4.0"
                ]
            ]
        },
        {
            "name": "pytest-asyncio",
            "specs": [
                [
                    ">=",
                    "1.0.0"
                ]
            ]
        }
    ],
    "lcname": "eg4-mcp-server"
}
        
Elapsed time: 2.30298s