emoncms-mcp-server

MCP (Model Context Protocol) server for the EmonCMS energy monitoring API. Allows AI assistants to query energy feeds, inputs, and historical data from your EmonCMS instance.

Features

• feed_list — List all feeds with current values and units
• feed_value — Get the current value of a specific feed
• feed_fetch — Get current values for multiple feeds at once
• feed_data — Get historical time-series data with configurable intervals
• feed_average — Get averaged data over time periods (hourly, daily, etc.)
• feed_daily — Get daily data points aligned to timezone (ideal for kWh/day)
• feed_meta — Get feed metadata (start time, interval, number of points)
• input_list — List all inputs grouped by node
• input_get — Get inputs for a specific node

Installation

npm install
npm run build

Configuration

The server requires two environment variables:

Variable	Required	Description
EMONCMS_URL	No	Base URL of your EmonCMS instance (default: http://192.168.1.250/emoncms)
EMONCMS_APIKEY	Yes	Your EmonCMS read API key

Usage with OpenCode

Add to your ~/.config/opencode/opencode.json:

{
  "mcpServers": {
    "emoncms": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/emoncms-mcp-server/dist/index.js"],
      "env": {
        "EMONCMS_URL": "http://192.168.1.250/emoncms",
        "EMONCMS_APIKEY": "your-read-api-key"
      }
    }
  }
}

Usage with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "emoncms": {
      "command": "node",
      "args": ["/path/to/emoncms-mcp-server/dist/index.js"],
      "env": {
        "EMONCMS_URL": "http://192.168.1.250/emoncms",
        "EMONCMS_APIKEY": "your-read-api-key"
      }
    }
  }
}

Tool Reference

feed_list

Lists all feeds with their current values.

No parameters required.

feed_value

Get the current value of a single feed.

Parameter	Type	Description
id	number	Feed ID

feed_fetch

Get current values for multiple feeds.

Parameter	Type	Description
ids	number[]	Array of feed IDs

feed_data

Get historical time-series data.

Parameter	Type	Description
id	number	Feed ID
start	string	Start time — ISO 8601 (e.g. 2024-01-01T00:00:00Z) or relative (-24h, -7d)
end	string?	End time (default: now)
interval	number?	Seconds between data points (default: 600)

feed_average

Get averaged data over intervals.

Parameter	Type	Description
id	number	Feed ID
start	string	Start time
end	string?	End time (default: now)
interval	number	Averaging interval in seconds (e.g. 3600 for hourly)

feed_daily

Get daily data points (timezone-aligned).

Parameter	Type	Description
id	number	Feed ID
start	string	Start time (e.g. -30d)
end	string?	End time (default: now)

feed_meta

Get metadata for a feed.

Parameter	Type	Description
id	number	Feed ID

input_list

Lists all inputs grouped by node.

No parameters required.

input_get

Get inputs for a specific node.

Parameter	Type	Description
node	string	Node name (e.g. emonpi, emontx3)

Development

npm run dev    # Run with tsx (hot reload)
npm run build  # Compile TypeScript
npm start      # Run compiled version

License

MIT