What is Emporia Mcp

The Emporia Energy MCP Server is a secure platform that allows LLM applications to access data from Emporia Energy devices. It is currently in BETA and may undergo changes in the future.

Use cases

Use cases include retrieving energy usage data, managing multiple devices, and integrating energy data into LLM applications for enhanced analytics and reporting.

How to use

To use the Emporia Energy MCP Server, it must be executed locally like a command line program. Users need to have a native Emporia Energy account to access the server functionalities.

Key features

Key features include secure authentication with automatic token refresh, comprehensive device listing, energy and power measurement retrieval with configurable time scales, well-structured API responses, and additional tools for EV Charger session/report details.

Where to use

The Emporia Energy MCP Server is primarily used in residential energy management, allowing users to monitor and analyze their energy consumption effectively.

Emporia Energy MCP Server

The Emporia Energy MCP Server provides a secure way for LLM applications to access your Emporia Energy device data. This MCP server implementation is in BETA and is subject to change moving forwards.

This MCP Server is implemented as a local stdio (transport) server requiring it to be executed locally similar to a command line program. We are currently investigating options for providing a remote SSE MCP server (hosted by Emporia Energy) that would allow for OAuth authentication flows however we don’t have an anticipated timeline of when this might be available.

This MCP server targets the Emporia Energy customer cloud - it does not support Partner related behavior.

Emporia Energy wants to hear any feedback or suggestions you might have related to this tool (or anything else we’re working on). Feel free to reach out with any questions/thoughts by emailing [email protected].

To learn more about Emporia Energy and what we’re building - feel free to visit our website at www.emporiaenergy.com. We also have a fairly expansive knowledge base about our products and platform available here: help.emporiaenergy.com.

Features

• Secure authentication with automatic token refresh
• Device listing with comprehensive device information
• Energy and Power measurement/usage data retrieval with configurable time scales and energy units
• Well-structured API responses with contextual information
• Additional EV Charger-related tools for session/report details

See Feature Status below for additional details on device specific implementation status and what will be coming in the future.

⚠️ Important Notes

• For the BETA implementation of this MCP server, you must have a native-Emporia Energy account. It will not work if you’ve created an Emporia Account using Google or Apple as third-party authentication providers. In the short-term, you can create a new account (with an email/password) and share your Emporia devices to the new account via the Emporia Energy web or mobile app. We expect that a future version of this MCP server program will have additional flexibility for these third-party provider accounts.
• Emporia accounts with many devices associated (> 20) may have issues with short context windows and long API responses. Similarly, requesting high amounts of measurement data can produce excessively large API responses that can cause problems for some clients and context-limited LLMs.
• LLM’s can be unreliable. While this MCP server program will provide accurate Emporia data from the cloud, the LLM’s interpretation (and requesting) of that data may be incorrect at times.

Examples

TODO

Tips/Tricks

• Be detailed when requesting specific dates/times of measurement data. Some clients/LLM’s may not provide up-to-date timestamps as part of their prompting process, so specifying exact time frames is usually helpful.
  + Instead of “show me last weeks usage”, try “show me usage from May 01, 2025 through May 10, 2025”
• Clarify if you’re looking for Power or Energy measurement/usage data as they have separate endpoints/tools (and would be used for separate purposes depending on your goals).
  + Instead of “show me usage”, try “show me energy usage for…” or “show me power measurements for…”

Release Notes

• May 23, 2025 - Initial release

Prerequisites

• Node.js 18+ (a Docker-based installation option may be available in the future)
• An Emporia Energy account (native account, not Google/Apple created)
• An MCP-capable AI client program (Claude Desktop, Cursor/Windsurf/VS Code, LM Studio/OpenWebUI, etc…)
  • see a list of example clients compiled by the official MCP project

Usage

Generating the MCP server file locally

You have to create a JavaScript server file locally. Your MCP client will run this file, you don’t need to leave the server running. See Option 3 below for Windows installation.

# Clone the repository
git clone https://github.com/emporiaenergy/emporia-mcp.git
cd emporia-mcp

# Install dependencies and build project
npm install && npm run build

Configuration in MCP Clients

To use this server within an MCP client, add it to your client’s MCP configuration file - using NPX is the recommended option (see below for details of running locally).
Authentication credentials (for your Emporia Energy account) must be provided either through environment variables or a .env file.

Option 1: Direct Environment Variables

{
  "mcpServers": {
    "emporia-mcp": {
      "command": "npx",
      "args": [
        "@emporiaenergy/emporia-mcp"
      ],
      "env": {
        "EMPORIA_ACCOUNT": "<YOUR_EMAIL>",
        "EMPORIA_PASSWORD": "<YOUR_PASSWORD>"
      }
    }
  }
}

Option 2: Using a .env File

You can provide your credentials in a .env file and specify its path using the ENV_FILE environment variable:

{
  "mcpServers": {
    "emporia-mcp": {
      "command": "npx",
      "args": [
        "@emporiaenergy/emporia-mcp"
      ],
      "env": {
        "ENV_FILE": "/path/to/your/.env"
      }
    }
  }
}

Example .env file contents:

[email protected]
EMPORIA_PASSWORD=examplepassword1234

Option 3: Using Node on Windows

There is an NPX bug on Windows, so use Node instead.

{
  "mcpServers": {
    "emporia-mcp": {
      "command": "node",
      "args": [
        "C:\\dev\\emporia-mcp-server\\build\\index.js"
      ],
      "env": {
        "EMPORIA_ACCOUNT": "<YOUR_EMAIL>",
        "EMPORIA_PASSWORD": "<YOUR_PASSWORD>",
        "DEBUG": "*"
      }
    }
  }
}

Feature Status

Available Tools

The server provides the following tools to help AI assistants interact with your Emporia Energy data:

1. listDevices
   Get an overview of all your connected Emporia Energy devices
   This tool provides a comprehensive inventory of your devices including customer information, device details (models, firmware versions), connection status, and location data. Use this to discover what devices are available for monitoring or control.

   Example response: Lists all your Vue energy monitors, EV chargers, and other Emporia devices with their current status and configuration details.

2. getDeviceDetails
   Get real-time status and details for any device type
   This tool returns detailed information about any of your Emporia devices (EV chargers, energy monitors, smart plugs, batteries, etc.) by passing one or more device serial numbers. The response includes relevant details for each device type, such as connection status, current state, charging rates, firmware, and more.

   Example response: For an EV charger, shows whether your vehicle is connected, actively charging, current charging rate (in amps), and maximum available charging rate. For an energy monitor, shows firmware version, channel counts, and device status. For a smart plug, shows on/off state and connection status. For a battery, shows state of charge, capacity, and power flows.

3. getDevicesChannels
   Get detailed information about device channels and circuit configurations
   This tool provides comprehensive information about all channels for your energy monitoring devices, including main and branch circuits. Essential for understanding your electrical system’s structure.

   Example response: Returns device channel configurations, showing main branch circuits, combined circuits, and channel naming/numbering that can be referenced in other API calls.

4. getDeviceEnergyUsage
   Analyze energy consumption of any device or circuit over time
   This tool retrieves historical energy usage data for any of your devices (EV chargers, energy monitors, smart plugs, batteries, etc.) with customizable time periods and resolutions. For devices with multiple circuits/channels (like energy monitors or batteries), you can specify which circuits to query.

   Example response: Returns time-series energy data (in kWh) for specified devices and (optionally) circuits, with timestamps and consumption values at your chosen resolution (from minutes to years).

5. getDevicePowerUsage
   Monitor real-time power draw from any device or circuit
   This tool provides power usage data showing how much electricity your devices or specific circuits are drawing at different times. Useful for understanding power consumption patterns across your electrical system.

   Example response: Returns time-series power data (in watts) for specified devices and (optionally) circuits, with timestamps and average power values at minute or 15-minute intervals.

6. getBatteryStateOfCharge
   Track Home Battery charge levels over time
   This tool provides historical state of charge (SoC) data for your home battery storage systems with customizable time periods and resolutions. Essential for understanding how your battery’s charge level fluctuates throughout the day, week, or month. Important note - for Home Battery systems only, not applicable for EVSE/Electric Vehicle SoC

   Example response: Returns time-series state of charge data (as percentage values 0-100%) for battery systems, with timestamps and average state of charge values at your chosen resolution (minutes, hours, or days).

7. getEVChargingReport
   Get comprehensive reports of your EV charging activity
   This tool provides detailed reports about your electric vehicle charging patterns, costs, and potential savings over a specified time period. Essential for understanding charging habits and optimizing for cost savings.

   Example response: Returns a comprehensive report including daily charging totals, individual charging sessions, energy usage (kWh), charging costs, and potential savings based on utility rate plans.

8. getEVChargerSessions
   Track plug-in and charging events for your EV chargers
   This tool provides detailed information about when vehicles were connected to your EV chargers and the charging sessions that occurred during those connection periods. Useful for understanding vehicle connection times and actual charging times.

   Example response: Returns a list of plug-in/plug-out events for each charger, including timestamps and energy usage data for each charging session within those connection periods.