# neoom BEAAM MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for the **neoom BEAAM** energy management system. It lets AI assistants like Claude query your solar production, battery state, grid power, and control devices using natural language.

## Features

- 🌤️ Real-time energy flow data (PV production, grid, battery, self-sufficiency)
- 🔋 Battery control (set charge/discharge power)
- ⚡ EV charger control (set max charging current)
- 🏠 Device inventory (list all connected Things and their data points)
- ☁️ **Two modes:** local BEAAM API (full control) or ntuity cloud API (remote read-only)
- 🔄 Automatic OAuth token refresh in cloud mode

## Requirements

- Node.js 18 or higher
- A [neoom BEAAM](https://neoom.com) device
- An API key from [neoom.com/developers](https://neoom.com/developers)

## Installation

```sh
git clone https://github.com/your-username/neoom-mcp.git
cd neoom-mcp
npm install
npm run build
```

## Configuration

The server supports two modes, auto-detected from environment variables.

### Local mode (recommended — full control, requires local network)

| Variable | Description |
|---|---|
| `BEAAM_IP` | IP address of your BEAAM on the local network (e.g. `192.168.1.100`) |
| `BEAAM_API_KEY` | Bearer API key from [neoom.com/developers](https://neoom.com/developers) |

### Cloud mode (remote access, read-only energy data)

| Variable | Description |
|---|---|
| `NTUITY_CLIENT_ID` | OAuth Client ID from [developer.neoom.com](https://developer.neoom.com) |
| `NTUITY_ACCESS_TOKEN` | OAuth access token (see setup below) |
| `NTUITY_REFRESH_TOKEN` | OAuth refresh token (see setup below) |
| `NTUITY_SITE_ID` | *(optional)* Pin to a specific site ID — skip the `list_sites` step |

#### Getting cloud tokens (one-time)

```sh
NTUITY_CLIENT_ID=<your_client_id> npm run oauth-setup
```

This opens your browser for neoom login, completes the PKCE OAuth flow, and prints the tokens to paste into your config.

## Usage with VS Code + GitHub Copilot

Create `.vscode/mcp.json` in this workspace (already gitignored to protect your secrets):

**Local mode:**
```json
{
  "servers": {
    "neoom-beaam": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/build/index.js"],
      "env": {
        "BEAAM_IP": "192.168.1.100",
        "BEAAM_API_KEY": "sk_beaam_..."
      }
    }
  }
}
```

**Cloud mode:**
```json
{
  "servers": {
    "neoom-beaam": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/build/index.js"],
      "env": {
        "NTUITY_CLIENT_ID": "your_client_id",
        "NTUITY_ACCESS_TOKEN": "your_access_token",
        "NTUITY_REFRESH_TOKEN": "your_refresh_token",
        "NTUITY_SITE_ID": "your_site_id"
      }
    }
  }
}
```

Then open Copilot Chat (`Cmd+Shift+I`), switch to **Agent mode**, and the tools will be available automatically.

## Usage with Claude for Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "neoom-beaam": {
      "command": "node",
      "args": ["/absolute/path/to/neoom-mcp/build/index.js"],
      "env": {
        "BEAAM_IP": "192.168.1.100",
        "BEAAM_API_KEY": "sk_beaam_..."
      }
    }
  }
}
```

## Usage with Claude Code CLI

```sh
claude mcp add --transport stdio neoom-beaam node -- /absolute/path/to/neoom-mcp/build/index.js
```

Set the env vars in your shell profile or prepend them when running Claude.

## Available Tools

### Local mode

| Tool | Description |
|---|---|
| `get_energy_flow` | Current grid/PV/battery/SoC/self-sufficiency values |
| `list_things` | All connected devices with IDs and DataPoint keys |
| `get_thing_states` | Per-device metrics by Thing ID |
| `set_battery_power` | Set battery `TARGET_POWER` in Watts (+charge / −discharge) |
| `set_ev_charger_limit` | Set EV charger `MAX_CURRENT_CHARGE` in Ampere |

### Cloud mode

| Tool | Description |
|---|---|
| `get_energy_flow` | Current energy flow (requires `site_id` or `NTUITY_SITE_ID`) |
| `list_sites` | All sites accessible to the authenticated account |

## Example Prompts

```
How much solar am I producing right now?
What is my battery state of charge?
Set my battery to charge at 3000W.
List all devices connected to my BEAAM.
What is the current state of my battery master?
Pause EV charging.
Am I currently exporting to the grid?
```

## Project Structure

```
src/
├── index.ts          # MCP server — tool registration, mode detection
├── neoom-client.ts   # Local BEAAM REST API client
├── ntuity-client.ts  # ntuity cloud API client with OAuth token refresh
└── oauth-setup.ts    # One-time CLI helper for cloud OAuth PKCE flow
build/                # Compiled JavaScript (run npm run build)
.vscode/
├── mcp.json          # Your local config with secrets (gitignored)
└── mcp.json.example  # Template to share with others
```

## Development

```sh
npm run build      # Compile TypeScript
npm run dev        # Watch mode (tsc --watch)
npm run oauth-setup  # Run cloud OAuth setup
```

## Security

- `.vscode/mcp.json` is **gitignored** — your IP and API keys will not be committed.
- Use `.vscode/mcp.json.example` as a template to share the config structure without secrets.
- Never commit `.env` files or tokens to version control.

## License

This project is licensed under the MIT License.