# emoncms-mcp-server

MCP (Model Context Protocol) server for the [EmonCMS](https://emoncms.org/) 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

```bash
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`:

```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`:

```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

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

## License

MIT