# Tesla Powerwall 2 MCP Server

A Model Context Protocol (MCP) server that provides tools to interact with your Tesla Powerwall 2 local gateway API. This allows AI assistants like Claude to monitor and control your Powerwall system.

## Features

### Authentication
- **powerwall_login** - Authenticate with your Powerwall gateway
- **powerwall_logout** - Expire your authentication token

### Monitoring Tools
- **powerwall_get_meters_aggregates** - Get real-time power metrics for solar, grid, battery, and home
- **powerwall_get_soe** - Get battery state of energy (charge percentage)
- **powerwall_get_system_status** - Get overall system status
- **powerwall_get_status** - Get Powerwall version and uptime
- **powerwall_get_site_info** - Get site configuration and capacity
- **powerwall_get_grid_status** - Check grid connection status
- **powerwall_get_powerwalls** - List all Powerwalls and their status
- **powerwall_get_meters** - Get detailed meter information
- **powerwall_get_solars** - Get solar array information

### Control Tools
- **powerwall_set_operation** - Change operation mode (self_consumption, backup, autonomous, scheduler)
- Set backup reserve percentage

### Configuration Tools
- **powerwall_get_operation** - View current operation mode settings
- **powerwall_get_config** - Get system configuration
- **powerwall_get_customer** - Get customer registration info
- **powerwall_get_installer** - Get installer information
- **powerwall_get_networks** - Get WiFi network information
- **powerwall_get_device_type** - Get device type details

## Installation

```bash
# Clone or create the project
npm install

# Build the TypeScript code
npm run build
```

## Configuration

Set these environment variables or create a `.env` file:

```bash
POWERWALL_HOST=192.168.1.xxx  # Your Powerwall gateway IP or hostname
POWERWALL_USERNAME=customer   # Usually "customer"
POWERWALL_PASSWORD=xxxxx      # Last 5 digits of gateway serial number or custom password
POWERWALL_EMAIL=              # Optional email
```

### Finding Your Credentials

1. **Gateway IP Address**: Check your router's connected devices or use the Tesla app
2. **Password**: 
   - Open the Tesla app
   - Go to Settings → My Home Info
   - Find "Powerwall Gateway" serial number
   - Use the last 5 digits as your password (unless you set a custom password)

## Usage with Claude Desktop

Add to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "tesla-powerwall": {
      "command": "node",
      "args": ["/path/to/tesla-powerwall-mcp/dist/index.js"],
      "env": {
        "POWERWALL_HOST": "192.168.1.xxx",
        "POWERWALL_USERNAME": "customer",
        "POWERWALL_PASSWORD": "xxxxx"
      }
    }
  }
}
```

## Example Queries for Claude

Once configured, you can ask Claude things like:

- "What's my current battery level?"
- "How much solar power am I generating right now?"
- "Show me all my power metrics"
- "What's my Powerwall operation mode?"
- "Change to self-consumption mode with 20% backup reserve"
- "Is the grid connected?"
- "What's my home power consumption?"
- "How many Powerwalls do I have?"

## Understanding Power Metrics

When you query `powerwall_get_meters_aggregates`, you'll see power values in watts:

- **site** (Grid): 
  - Positive = drawing power from grid
  - Negative = sending power to grid
- **battery** (Powerwall):
  - Positive = discharging (powering home)
  - Negative = charging
- **solar**:
  - Positive = generating power
- **load** (Home):
  - Power being consumed by your home

## Operation Modes

- **self_consumption**: Use solar/battery to power home, grid as backup
- **backup**: Prioritize keeping battery charged for outages
- **autonomous**: Time-based control (if configured)
- **scheduler**: Custom schedule mode

## Security Notes

⚠️ **Important Security Considerations**:

1. **Self-Signed Certificate**: The Powerwall uses a self-signed SSL certificate. This server accepts it by setting `rejectUnauthorized: false`. This is standard for local Powerwall access but means SSL verification is disabled.

2. **Local Network Only**: Only use this on your trusted local network. Never expose your Powerwall gateway to the internet.

3. **Credentials**: Keep your gateway password secure. Anyone with access can control your Powerwall.

4. **Token Storage**: Authentication tokens are stored in memory only during the session.

## API Reference

Based on the community-documented API at: https://github.com/vloschiavo/powerwall2

## Troubleshooting

**Cannot connect to Powerwall:**
- Verify the IP address is correct
- Make sure you're on the same network as your Powerwall
- Check firewall settings

**Authentication fails:**
- Verify password is correct (last 5 digits of gateway serial)
- Try using the custom password if you set one
- Some firmware versions may require different authentication

**"Error: self signed certificate":**
- This is expected. The server handles self-signed certificates automatically.

## Project Structure

```
tesla-powerwall-mcp/
├── src/
│   └── index.ts          # Main MCP server code
├── dist/                 # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md
```

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run directly
npm start
```

## Contributing

Contributions welcome! This server implements the documented endpoints from the community research at https://github.com/vloschiavo/powerwall2

## License

MIT

## Disclaimer

This is an unofficial tool and is not affiliated with Tesla, Inc. Use at your own risk. The author is not responsible for any issues that arise from using this software to interact with your Powerwall system.

## Credits

- API documentation: https://github.com/vloschiavo/powerwall2
- MCP Protocol: Anthropic
- Community research and testing by Tesla Powerwall owners