What is MCP?
Imagine opening a chat window and simply asking: “How much did my EV charger cost me last week?”…and getting an instant, accurate answer that’s pulled straight from the Emporia cloud.
That’s exactly what the Emporia Model Context Protocol (MCP) Server is for. It sits quietly on your computer, pulls your Emporia data into an AI model when you ask, and stays out of the way when you don’t.
Below is a friendly walk-through aimed at anyone who’s never touched a command line in their life.
If you can install an app and copy-and-paste some text, you can have this up and running within a few minutes.
Emporia MCP is for a local MCP implementation (where it runs on your computer). A remote (SSE) version of this MCP program (hosted by Emporia Energy) is on the "todo" list.
What you need:
1.) An Emporia Account with email and password.
If you signed up with Google or Apple, make a fresh “native” account (with an email and password) and share your devices with it. This local MCP implementation does not work with third-party authenticated accounts at the moment.
2.) A chat app (aka "client") that speaks MCP.
Think of it as the messenger that will talk to your data. Claude Desktop, Cursor, VS Code extensions (like RooCode, Cline), LibreChat — pick your favorite.
The official MCP project website also has a thorough list of available clients you can use.
ChatGPT (OpenAI) currently only supports remote (SSE) implementations of MCP servers. We're hoping to build a remote version that would be ChatGPT compatible in the future.
3.) Node.js installed on your computer.
This is just a helper behind the scenes - Node.js allows the Emporia MCP server code to run on your computer.
Install Node.js and verify it is working
1.) Open Terminal (on mac) or Command Prompt (on windows)
2.) Type the following (and press Enter):
node -v
Did you see a version number returned? Perfect! You're good to go with Node setup locally.
Did you receive a "Command not found" error or similar? Try installing Node via this link - restart your terminal afterward and retry.
Choose how your credentials are stored
1.) Inline Environment Variables (RECOMMENDED!)
Quick copy-paste, no extra file. Simplest method for non-technical users.
For simplicity, most examples in this article use this option.
"env": {
"EMPORIA_ACCOUNT":"[email protected]",
"EMPORIA_PASSWORD":"examplePassword1234"
}2.) Using a .env File
Keeps passwords out of plain config, easy to rotate. Quickly add your file path for the "ENV_FILE" variable and you'll be up and running.
"env": {
"ENV_FILE":"/path/to/your/.env"
}If using a .env file to store credentials, you'll want "EMPORIA_ACCOUNT" and "EMPORIA_PASSWORD" defined within the file like:
[email protected]
EMPORIA_PASSWORD=examplePassword1234
Update your client Settings
Windows Users - you'll want to use Option #2 given there is a known NPX-related bug for Claude Desktop and other clients.
For a complete walkthrough for Claude Desktop or Cursor IDE - see these links:
For other MCP-capable AI clients, you should only need to add similar configuration options to your client-specific settings. Here's an example of what the "JSON" might look like for a standard MCP client:
{
"mcpServers":{
"emporia-mcp":{
"command":"npx",
"args":["@emporiaenergy/emporia-mcp"],
"env":{
"EMPORIA_ACCOUNT":"[email protected]",
"EMPORIA_PASWORD":"examplePassword1234"
}
}
}
}Windows users will want to have a slightly different configuration:
{
"mcpServers":{
"emporia-mcp":{
"command":"node",
"args":["C:\\dev\\emporia-mcp-server\\build\\index.js"],
"env":{
"EMPORIA_ACCOUNT":"[email protected]",
"EMPORIA_PASSWORD":"examplePassword1234"
}
}
}
}Important to note the different "command" as well as provide the file path of the local MCP installation.
Once you've updated your client settings - it is often helpful to restart your client to make sure it has been saved correctly.
First Commands to Try
"List my Emporia devices."
should return a list of your Emporia devices with a bit of detail
"Show me the Power measurements for my EV Charger on May 31st, 2025"
should return a description and some details about your EV Chargers usage from a specific date, can also query charging sessions/reports
"What was my battery system's average State of Charge during the month of May?"
should query the Emporia cloud for home battery details, and summarize/calculate average SoC for the appropriate time period
"Visualize my energy monitors mains usage over the past two weeks"
many advanced AI models like Claude 3.5 or higher are capable of "coding" visualizations for data sets and more