Skip to main content
Glama
thorstenroth4040

neoom BEAAM MCP Server

by thorstenroth4040
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

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

Related MCP server: Fronius MCP Server

Requirements

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.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Home Assistant MCP Server

    mjrestivo16
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to interact with Home Assistant smart home devices through natural language. Control devices, manage automations, query entity states, and retrieve historical data across your home automation system.
    1
    MIT

  • Fronius MCP Server

    huber
    A
    license
    A
    quality
    D
    maintenance
    Enables access to Fronius solar inverter data via the MCP protocol, allowing real-time monitoring of energy production, consumption, and battery storage through natural language.
    14
    20 npm
    4
    MIT

  • anker-solix-mcp

    gkoenig
    A
    license
    A
    quality
    B
    maintenance
    Enables LLM agents to query live data from Anker Solix solar systems (Solarbank, expansion batteries, Smartmeter) via natural language, such as current solar production or battery state of charge.
    12
    1
    MIT