neoom BEAAM MCP Server

A Model Context Protocol (MCP) 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 device
• An API key from neoom.com/developers

Installation

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

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

Variable	Description
NTUITY_CLIENT_ID	OAuth Client ID from 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)

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:

{
  "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:

{
  "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:

{
  "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

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

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.