Foxess MCP Server

FoxESS MCP服务器

🚀⚡ FoxESS太阳能逆变器模型上下文协议服务器

强大的MCP服务器，使Claude等AI助手能够访问、分析和优化来自FoxESS逆变器的太阳能数据。

✨ 特性

• 🔍 实时分析：访问实时太阳能发电和消费数据
• 📊 历史见解：分析几天、几周和几个月的能量模式
• 🩺 系统诊断：自动健康检查和性能监控
• 🔮 智能预测：人工智能驱动的能源预测和优化
• 🔒 安全集成：基于令牌的身份验证和数据净化
• ⚡ 高性能：智能缓存和速率限制
• 🛠️ 轻松设置：一键安装为Claude Desktop扩展

🎯 核心工具

1. foxess_analysis

实时和历史能源数据的全面数据收集和处理。

示例用法：

Analyze my solar system's performance over the last week, focusing on PV generation and battery usage.

2. foxess_diagnosis

自动系统健康评估，并提供性能优化建议。

示例用法：

Run a comprehensive health check on my FoxESS system and identify any issues.

3. foxess_forecast

根据历史数据和天气模式生成能源预测和优化策略。

示例用法：

Forecast my daily energy yield for the next week and suggest battery optimization settings.

🚀 快速开始

先决条件

• Python 3.10或更高版本
• Claude桌面应用程序
• 具有云连接的FoxESS逆变器
• 具有API访问权限的FoxESS云帐户

安装

1. 获取您的FoxESS API代币

⚠️ 重要：API密钥生成仅在 旧版v1门户!

- 访问传统门户： Foxesscloud.com/login - 导航到个人中心→ API管理 - 生成您的私人API令牌 - 复制您的设备序列号

> 备注：新的v2门户(foxesscloud.com/v2/login)确实如此 不 支持API密钥生成。您必须使用遗留的v1门户来创建API令牌。 > > 有关API文档，请参阅 官方FoxESS Open API文档.

1. 安装MCP服务器

   # Clone the repository
   git clone https://github.com/holger1411/foxess-mcp-server.git
   cd foxess-mcp-server

   # Create and activate virtual environment (recommended)
   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

   # Upgrade pip to latest version
   pip install --upgrade pip

   # Install dependencies
   pip install -r requirements.txt

   # Install the package
   pip install -e .

1. 配置Claude桌面

添加到您的 claude_desktop_config.json:

   {
     "mcpServers": {
       "foxess-mcp-server": {
         "command": "/path/to/foxess-mcp-server/venv/bin/python",
         "args": ["-m", "foxess_mcp_server"],
         "env": {
           "FOXESS_API_KEY": "your-api-token-here",
           "FOXESS_DEVICE_SN": "your-device-serial-here"
         }
       }
     }
   }

备注：替换 /path/to/foxess-mcp-server/ 使用您的实际安装路径。您可以通过以下方式找到它：

   pwd  # Run this inside your foxess-mcp-server directory

1. 验证安装

重新启动Claude Desktop并尝试：

   Can you check my solar system's current status?

🔧 故障排除

安装问题

问题: ERROR: Could not find a version that satisfies the requirement mcp>=1.0.0

解决方案：使用Python\<3.10时会发生此错误。MCP库需要Python 3.10或更高版本。

1. 检查你的Python版本：

   python3 --version

1. 如果你的Python\<3.10，请使用以下命令安装Python 3.10+：

   # macOS with Homebrew
   brew install python@3.10

   # Or update to latest Python
   brew install python@3.12

1. 使用正确的Python版本创建虚拟环境：

   python3.10 -m venv venv  # or python3.12
   source venv/bin/activate
   pip install --upgrade pip
   pip install -r requirements.txt
   pip install -e .

问题: Defaulting to user installation because normal site-packages is not writeable

解决方案：使用虚拟环境以避免权限问题：

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

📊 支持的数据点

能量流

• 太阳能发电：光伏功率输出，串级数据
• 能源消耗：房屋负荷、电网消耗
• 电池操作：充电/放电功率和能量
• 网格交互：馈入功率、电网消耗

系统状态

• 电池健康：充电状态、电压、电流、温度
• 网格参数：电压、频率、电流
• 系统温度：逆变器和环境温度
• 状态代码：操作状态、故障代码、警告

历史数据

• 能源总量：每日/每月发电量和消耗量
• 性能指标：效率计算和趋势
• 运营历史：系统事件和维护需求

⚙️ 配置

环境变量

高级配置

创建自定义配置文件：

{
  "cache_ttl_minutes": 5,
  "max_concurrent_requests": 3,
  "request_timeout_seconds": 30,
  "rate_limit_enabled": true
}

🔒 安全与隐私

• 令牌安全：API令牌从未被记录或公开
• 数据的清理：所有日志都会自动清理
• 速率限制：自动遵守FoxESS API限制
• 输入验证：所有用户输入都经过验证和消毒
• 安全存储：通过Claude Desktop使用操作系统本机凭据存储

📈 演出

• 智能缓存：多级缓存可实现最佳性能
• 速率限制：自动符合FoxESS API限制
• 连接池：高效的HTTP连接管理
• 内存优化：可配置的内存限制和清理

🧪 发展

建立开发环境

# Clone and enter directory
git clone https://github.com/holger1411/foxess-mcp-server.git
cd foxess-mcp-server

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

# Install development dependencies
pip install -r requirements-dev.txt
pip install -e .

# Run tests
pytest

# Run linting
black src/
isort src/
mypy src/

项目结构

foxess-mcp-server/
├── src/foxess_mcp_server/     # Main package
│   ├── server.py              # MCP server entry point
│   ├── foxess/                # FoxESS API integration
│   ├── tools/                 # MCP tools implementation
│   ├── cache/                 # Caching system
│   └── utils/                 # Utilities and helpers
├── config/                    # Configuration files
├── tests/                     # Test suite
└── manifest.json              # MCP extension manifest

🤝 贡献

欢迎投稿！以下是您可以做出贡献的一些方式：

• 🐛 错误报告：通过以下方式报告问题和错误
• 💡 功能请求：建议新功能
• 📝 文档：改进文档和示例
• 🧪 测试：添加测试并提高覆盖率
• 💻 代码：提交拉取请求

🔗 链接

• 🌐 网站: holgerkoenemann.com
• 📖 文档:
• 📚 FoxESS API文档: FoxESS开放式API文档
• 🐛 错误报告:
• 📦 发布:

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🌟 致谢

• 狐狸 用于提供云API
• Anthropic 对于模型上下文协议
• 社区贡献者 感谢他们的宝贵意见和贡献

🆘 支持

需要帮助？以下是如何获得支持：

1. 搜索 现有问题
2. 检查 维基 用于文件编制
3. 创建一个 新问题 如有需要