Content
# MirAIe AC MCP
Python package and MCP server for controlling MirAIe air conditioner devices.
## Features
- Discover available MirAIe AC devices.
- Power control (`turn_on_device`, `turn_off_device`) for one or all devices.
- Set temperature, fan mode, HVAC mode, presets, and swing positions.
- Query device details and friendly names through MCP tools.
## Repository Structure
```text
src/miraie_ac_mcp/
api.py
broker.py
constants.py
device.py
device_status.py
enums.py
exceptions.py
home.py
manager.py
server.py
user.py
utils.py
tests/
docs/
```
## Requirements
- Python 3.13+
- [uv](https://docs.astral.sh/uv/) (recommended)
## Setup
1. Create and activate an environment:
```bash
uv venv
source .venv/bin/activate
```
2. Install package and dev dependencies:
```bash
uv sync --extra dev
```
3. Configure credentials:
```bash
cp .env.example .env
```
Update `.env`:
```env
MIRAIE_LOGIN_ID=your_phone_number_or_email
MIRAIE_PASSWORD=your_password
```
## Run MCP Server
```bash
uv run python -m miraie_ac_mcp.server
```
## MCP Client Configuration
Example config snippet:
```json
{
"mcpServers": {
"miraie-ac-mcp": {
"command": "uv",
"args": [
"run",
"python",
"-m",
"miraie_ac_mcp.server"
],
"env": {
"MIRAIE_LOGIN_ID": "your_login",
"MIRAIE_PASSWORD": "your_password"
}
}
}
}
```
## Tooling
Run tests:
```bash
uv run pytest
```
Run lint checks:
```bash
uv run ruff check .
```
Format code:
```bash
uv run ruff format .
```
## Notes
- Tool calls that require live device access need valid MirAIe credentials and network connectivity.
- Unit tests mock network-dependent behavior and run offline.
# Panasonic MirAIe AC MCP Server
A Model Context Protocol (MCP) server that enables control of Panasonic MirAIe air conditioning devices through conversational AI. This server provides comprehensive AC control capabilities including temperature setting, mode changes, fan control, and device management.
## Features
### Device Control
- **Power Management**: Turn devices on/off individually or all at once
- **Temperature Control**: Set temperature (16-30°C) for specific devices or all devices
- **Mode Control**: Switch between operating modes (auto, cool, heat, dry, fan)
- **Fan Control**: Adjust fan speed (auto, low, medium, high)
- **Preset Modes**: Set energy-saving presets (none, eco, boost)
### Advanced Controls
- **Swing Control**:
- Vertical swing modes (positions 0-5)
- Horizontal swing modes (positions 0-5)
- **Device Management**:
- List all connected devices
- Get detailed device information
- Individual device targeting by name
### Supported Operations
- `get_device_status` - List all available AC devices
- `turn_on_device` - Power on specific device or all devices
- `turn_off_device` - Power off specific device or all devices
- `set_temperature` - Set temperature for specific device or all devices
- `set_fan_mode` - Control fan speed settings
- `set_mode` - Change AC operating mode
- `set_preset_mode` - Apply energy presets
- `set_vertical_swing_mode` - Control vertical air direction
- `set_horizontal_swing_mode` - Control horizontal air direction
- `get_device_details` - Get comprehensive device information
## Requirements
### Python Dependencies
```
mcp>=0.1.0
python-dotenv
asyncio
fastapi (optional, for REST API)
```
### Environment Setup
The server requires Panasonic MirAIe account credentials configured as environment variables:
```bash
MIRAIE_LOGIN_ID=your_phone_number_or_email
MIRAIE_PASSWORD=your_password
```
## Installation & Setup
### 1. Clone and Install Dependencies
```bash
#THEN
cd miraie_mcp
pip install mcp python-dotenv
```
### 2. Configure Environment
Create a `.env` file in the project root:
```env
MIRAIE_LOGIN_ID=your_phone_number_or_email
MIRAIE_PASSWORD=your_password
```
A sample env is also provided as .env.sample
### 3. MCP Configuration
Add to your MCP client configuration (e.g., Claude Desktop config):
```json
{
"mcpServers": {
"panasonic-miraie-ac": {
"command": "python",
"args": ["/path/to/miraie_mcp/miraie_mcp.py"],
"env": {
"MIRAIE_LOGIN_ID": "83770.....",
"MIRAIE_PASSWORD": "djawesom....(yourpassword)"
}
}
}
}
```
### 4. Run the Server
```bash
python miraie_mcp.py
```
## Usage Examples
### Basic Device Control
```
# Turn on all AC units
"Turn on all AC devices"
# Turn off a specific device
"Turn off the living room AC"
# Set temperature for all devices
"Set all ACs to 24 degrees"
# Set temperature for specific device
"Set the bedroom AC to 22 degrees"
```
### Mode and Fan Control
```
# Change operating mode
"Set all ACs to cooling mode"
"Switch bedroom AC to auto mode"
# Adjust fan speed
"Set fan to high speed for all devices"
"Change living room AC fan to low"
# Apply presets
"Set all ACs to eco mode"
"Enable boost mode for bedroom AC"
```
### Advanced Controls
```
# Control swing modes
"Set vertical swing to position 3 for all ACs"
"Change horizontal swing to auto for bedroom AC"
# Get device information
"Show me all available AC devices"
"Get details for the living room AC"
```
## FastAPI Integration
The project includes an optional FastAPI server (`fastapi_server.py`) for REST API access:
```bash
uvicorn fastapi_server:app --reload
```
### API Endpoints
- `GET /devices` - Get all device status
- `POST /devices/on` - Turn on all devices
- `POST /devices/off` - Turn off all devices
- `POST /devices/temperature` - Set temperature for all devices
- `POST /device/control` - Control specific device
## Architecture
### Core Components
- **`miraie_mcp.py`** - Main MCP server implementation
- **`api.py`** - Panasonic MirAIe API client
- **`device.py`** - Device abstraction and control logic
- **`enums.py`** - Enumeration definitions for modes and states
- **`fastapi_server.py`** - Optional REST API server
### Authentication Types
Supports multiple authentication methods:
- Mobile phone number
- Email address
- Username
### Device Management
- Automatic device discovery upon connection
- Context-managed device connections
- Error handling and device validation
- Support for multiple simultaneous devices
## Troubleshooting
### Common Issues
1. **Authentication Errors**: Verify credentials in `.env` file
2. **Device Not Found**: Check device name spelling and availability
3. **Connection Issues**: Ensure stable internet connection
4. **Permission Errors**: Verify MirAIe account has device access
### Debug Mode
Enable debug logging by setting stderr output in the terminal:
```bash
python miraie_mcp.py 2>debug.log
```
## Security Notes
- Store credentials securely using environment variables
- Never commit credentials to version control
- Use secure network connections for device communication
- Regularly update authentication tokens
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly with actual devices
5. Submit a pull request
## License
Feel free to use.
## Support
For issues and support:
1. Check the troubleshooting section
2. Review device compatibility
3. Open an issue with detailed error logs
4. Include device model and network setup details
