The Emporia Model Context Protocol (MCP) Server enables you to use any MCP-compatible AI tool to interact with your Emporia energy data in a brand new way. Ask questions in natural language, create custom visualizations, and analyze your energy usage—all through your favorite AI chat interface.
This guide walks you through setting up the Emporia MCP server on your computer. If you can install an app and copy and paste text, you can have this running in just a few minutes.
Note: This is a local MCP implementation that runs on your computer. A remote (SSE) version hosted by Emporia Energy is on our development roadmap.
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 pulled straight from the Emporia cloud.
That's exactly what the Emporia Model Context Protocol (MCP) Server does. It sits quietly on your computer, connects your Emporia data to AI models when you ask questions, and stays out of the way when you don't need it.
Real-World Examples:
"Show me my energy usage patterns for the last month."
"What was my peak demand yesterday?"
"Create a chart comparing weekday versus weekend usage."
"How much solar energy did I generate last week?"
What You Need
1. An Emporia Account with Email and Password
If you signed up with Google or Apple, create a new "native" account with email and password
Share your devices with the new account
This local MCP implementation does not currently work with third-party authenticated accounts
2. An MCP-Compatible Chat Client
Think of this as the messenger that talks to your data. Popular options include:
Claude Desktop
Cursor
VS Code extensions (RooCode, Cline)
LibreChat
The official MCP project website has a thorough list of available clients you can use.
Note: ChatGPT (OpenAI) currently only supports remote (SSE) implementations of MCP servers. We're hoping to build a ChatGPT-compatible remote version in the future.
3. Node.js Installed on Your Computer
Node.js is a helper that runs behind the scenes, allowing the Emporia MCP server code to run on your computer.
Installing and Verifying Node.js:
Open Terminal (Mac) or Command Prompt (Windows)
Type the following command and press Enter:
node -v
If you see a version number: Perfect! You're ready to proceed.
If you receive a "Command not found" error: Install Node.js from nodejs.org/en/download, restart your terminal, and try again.
Choose How Your Credentials Are Stored
Inline Environment Variables (RECOMMENDED)
Quick copy-paste, no extra file needed. This is the simplest method for most users.
"env": { "EMPORIA_ACCOUNT":"[email protected]", "EMPORIA_PASSWORD":"examplePassword1234" }Most examples in this article use this option for simplicity.
Using a .env File
Keeps passwords out of plain config files and makes credential rotation easier. Add your file path for the "ENV_FILE" variable.
"env": { "ENV_FILE":"/path/to/your/.env" }If using a .env file, define your credentials within the file like this:
[email protected] EMPORIA_PASSWORD=examplePassword1234
Update Your Client Settings
Important for Windows Users: Use Option #2 below due to a known NPX-related bug in Claude Desktop and other clients.
For Complete Setup Guides:
Option 1: Standard Configuration (Mac/Linux)
For other MCP-capable AI clients, add this configuration to your client-specific settings:
{ "mcpServers":{ "emporia-mcp":{ "command":"npx", "args":["@emporiaenergy/emporia-mcp"], "env":{ "EMPORIA_ACCOUNT":"[email protected]", "EMPORIA_PASSWORD":"examplePassword1234" } } } }Option 2: Windows Configuration
Windows users need 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: Note the different "command" value and provide the file path of your local MCP installation.
After Updating: Restart your client to ensure settings are saved correctly.
First Commands to Try
Once configured, test your setup with these example queries:
List Devices:
"List my Emporia devices."
Should return a list of your devices with details
Query Specific Data:
"Show me the power measurements for my EV Charger on May 31st, 2025."
Should return usage details from the specified date
Calculate Averages:
"What was my battery system's average State of Charge during May?"
Should query and summarize battery data for the time period
Create Visualizations:
"Visualize my energy monitor's mains usage over the past two weeks."
Advanced AI models like Claude 3.5 can create charts and graphs from your data
Helpful Resources
Official Links:
Feedback and Suggestions
This knowledge base is continuously evolving to provide comprehensive support for managing your energy effectively. If you found this article unhelpful or think it could be improved, please contact our Customer Support team.