mcp-fsolar

Live Felicity Solar battery data for Claude, REST APIs, Node.js apps, and event-driven pipelines — all from one package.

Connects to the Felicity Solar cloud and exposes per-cell voltages, SOC, SOH, temperatures, BMS counters, balancing state, and computed health metrics.

Usage modes

| Mode | When to use | |---|---| | MCP server → Claude | Ask Claude natural-language questions about your batteries | | Standalone REST API | Query battery data over HTTP from any language or tool | | JS / TS library | Embed directly in a Node.js or Next.js app — no separate server | | Event-driven | React to battery events (alerts, periodic snapshots) via webhooks or EventEmitter |

MCP server → Claude

The same fsolar-mcp process serves both MCP and REST from one port.

Claude Code (CLI)

Start the server manually, then register it:

npm install -g fsolar-mcp
[email protected] FELICITY_PASS=yourpass fsolar-mcp

claude mcp add felicity --transport sse http://localhost:3010/sse

Or let Claude Code auto-launch it on demand — no separate terminal needed. Run once to register:

claude mcp add felicity \
  -e [email protected] \
  -e FELICITY_PASS=yourpass \
  -- npx fsolar-mcp

Credentials tip: the -e KEY=val flags appear in shell history. To avoid that, store credentials in .env and use the JSON config approach (Claude Desktop / Cursor sections below) — credentials stay in the config file, not the command line.

Claude Code launches a fresh fsolar-mcp process for each session (via stdio) and kills it when done. Each process starts its own poller, so get_balance_trend needs ~10 min of uptime before trend data is available.

Ask Claude things like "what's the battery SOC?", "is any cell imbalanced?", or "show me the cell voltages for Bat2".

Claude Desktop

Open Claude Desktop → Settings → Developer → Edit Config and add:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "felicity": {
      "command": "npx",
      "args": ["fsolar-mcp"],
      "env": {
        "FELICITY_USER": "[email protected]",
        "FELICITY_PASS": "yourpassword"
      }
    }
  }
}

Restart Claude Desktop — a hammer icon appears in the toolbar when the server is connected.

Cursor

Add to .cursor/mcp.json in your project root (or the global ~/.cursor/mcp.json):

{
  "mcpServers": {
    "felicity": {
      "command": "npx",
      "args": ["fsolar-mcp"],
      "env": {
        "FELICITY_USER": "[email protected]",
        "FELICITY_PASS": "yourpassword"
      }
    }
  }
}

Any MCP client (SSE transport)

Start the server, then point your client at the SSE endpoint:

http://localhost:3010/sse

The MCP message endpoint is http://localhost:3010/messages?sessionId=<id> (handled automatically by the SDK).

Auth note: when FELICITY_API_KEY is set, /sse requires the same auth header as every other endpoint. Add "X-API-Key": "your-key" to your MCP client's SSE headers config.

MCP tools

| Tool | Description | |---|---| | get_all_batteries | Live status of all batteries — SOC, power, voltage, temperature, charging state | | get_battery | Detailed status of one battery by alias (Bat1) or serial number | | get_cell_voltages | Individual cell voltages (mV) — useful for detecting cell imbalance | | get_fleet_summary | Compact health summary: total energy, worst cell delta, temperatures | | get_balance_trend | Cell delta trend over the last ~60 min (improving / stable / degrading) | | get_snapshots | Raw snapshots for the last ~60 min (one per ~10 min) | | get_health | Per-battery health: cell delta status, temperature, SOH, outlier cells, C-rate | | get_autonomy | Fleet autonomy: hours until pack hits minSoc, hours to full, SOC-at-sunrise projection | | get_alerts | Active alert list ranked by severity (CRIT/WARN/INFO) | | get_energy_history | Daily charge/discharge kWh totals up to 90 days — peak power and net balance | | get_cell_stats | Per-cell voltage statistics: mean, stddev, min/max, deviation from pack average, trend | | get_module_health | Per-module voltage aggregates (min/max/mean/delta) with outlier-cell flags | | get_limit_headroom | Headroom to BMS protection limits — voltage and current headroom per battery | | get_lifetime_stats | Cycle count, full-charge events, under-voltage events, remaining LFP cycle life | | get_capacity_estimate | Estimated real capacity vs rated capacity per battery | | get_power_stats | Peak/average charge and discharge kW, C-rate, fraction above 0.5C | | get_cost_savings | Estimated monetary savings from discharged energy × tariff |

Standalone REST API

The same fsolar-mcp process exposes a plain HTTP API on the same port. No MCP client needed — any language or tool that can make HTTP requests works.

npm install -g fsolar-mcp
[email protected] FELICITY_PASS=yourpass fsolar-mcp

Endpoint reference

| Method | Path | Description | |---|---|---| | GET | /batteries | All batteries — SOC, power, voltage, temperature, charging state | | GET | /batteries/:id | One battery by alias (Bat1) or serial number | | GET | /batteries/:id/cell-stats | Per-cell voltage statistics from intraday snapshots | | GET | /batteries/:id/module-health | Per-module voltage aggregates with outlier flags | | GET | /alerts | Active alert list ranked by severity (?id= to filter one battery) | | GET | /energy | Daily charge/discharge kWh history up to 90 days | | GET | /limit-headroom | Voltage/current headroom to BMS limits (?id= to filter) | | GET | /lifetime-stats | Cycle count, full-charges, under-voltage events (?id= to filter) | | GET | /capacity | Estimated vs rated capacity with degradation % (?id= to filter) | | GET | /power-stats | Peak/average power and C-rate statistics from snapshots | | GET | /cost-savings | Energy savings estimate (?tariff= override, else FELICITY_TARIFF_KWH) | | GET | /events | Real-time SSE stream — snapshot events every 30 s; state on connect | | GET | /snapshots/intraday | Download intraday snapshot store (JSON file) | | GET | /snapshots/daily | Download daily snapshot store (JSON file) | | GET | /snapshots/state | Download latest persisted state (JSON file) | | DELETE | /snapshots/intraday | Clear intraday snapshot history | | DELETE | /snapshots/daily | Clear daily snapshot history | | DELETE | /snapshots/all | Clear all snapshot stores | | POST | /hooks | Register a webhook URL | | GET | /hooks | List registered webhooks | | GET | /hooks/:id/deliveries | Delivery log for a hook (last 50, newest first) | | DELETE | /hooks/:id | Remove a webhook | | GET | /health | Server health — uptime, version, last poll error | | GET | /sse | MCP SSE transport endpoint (requires auth when FELICITY_API_KEY is set) |

Examples

# all batteries
curl http://localhost:3010/batteries

# one battery
curl http://localhost:3010/batteries/Bat1

# download snapshot history for analysis
curl http://localhost:3010/snapshots/intraday -o intraday.json
curl http://localhost:3010/snapshots/daily    -o daily.json

# register a webhook for all events
curl -X POST http://localhost:3010/hooks \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://your-server.com/webhook"}'

GET /batteries response shape:

{
  "batteries": [
    {
      "alias": "Bat1",
      "soc": 87,
      "soh": 98,
      "chargingState": "charging",
      "power": 1240,
      "voltage": 53.2,
      "current": 23.3,
      "cellDelta": 12,
      "tempMin": 28,
      "tempMax": 31,
      "remainingKwh": 8.7,
      "isBalancing": false,
      "cellVoltages": [3310, 3312, 3308, "…16 cells total"]
    }
  ],
  "fetchedAt": "2025-06-01T12:00:00.000Z",
  "fromCache": true,
  "pollError": null
}

GET /batteries/:id response shape:

{
  "battery": { "…full battery object including modules…" },
  "fetchedAt": "2025-06-01T12:00:00.000Z",
  "fromCache": true
}

Pass X-Last-Fetched-At: <ISO timestamp> to bypass the cache when you already hold fresh data.

JS / TS library

Import the client directly in your app — no separate server or network hop required. The library handles RSA login, token refresh, and caching internally.

import { FelicityClient, MemoryCacheAdapter } from 'fsolar-mcp'

const client = new FelicityClient({
  user: process.env.FELICITY_USER,
  pass: process.env.FELICITY_PASS,
  cache: new MemoryCacheAdapter(),
  ttl: 30,  // cache TTL in seconds
})

const { batteries } = await client.getBatteries()
const { battery }   = await client.getBattery('Bat1')

To also start the background poller (keeps data fresh, enables snapshots and events):

import { FelicityClient, MemoryCacheAdapter, startPoller } from 'fsolar-mcp'

const client = new FelicityClient({ user, pass, cache: new MemoryCacheAdapter(), ttl: 30 })
startPoller(client)   // polls every FELICITY_POLL_MS (default 30 s)

TypeScript types are generated from source — the package ships dist/index.d.ts automatically. No separate @types package needed.

TypeScript

The package is written in TypeScript. All types are exported from the package root:

import type {
  Battery, BatteryModule,
  BatteryHealth, AutonomyResult, AutonomyPerBattery, AutonomyOptions,
  BatterySnapshot, BalanceTrend,
  BatteriesResult, BatteryResult,
  FelicityClientOptions,
  MaterializedState,
  SnapshotPayload,
  CacheAdapter,
  // Analytics
  Alert, EnergyDay, CellStat, PowerStats,
  // Persistent energy store
  DailyEnergy,
} from 'fsolar-mcp'

import { ChargingState, HealthStatus, TrendDirection, HookEvent,
         AlertSeverity } from 'fsolar-mcp'
import { DailyEnergyStore, dailyEnergyStore } from 'fsolar-mcp'

Battery

The core data object — one per physical battery pack. Returned inside BatteriesResult and BatteryResult.

interface Battery {
  // Identity
  sn:    string               // serial number
  alias: string               // human name (Bat1, Bat2, …)
  model: string               // model string from BMS
  status: "NM" | "AL" | "FL" | "OF"  // Normal / Alarm / Fault / Offline

  // State of charge / health
  soc: number                 // % state of charge
  soh: number                 // % state of health

  // Electrical
  voltage: number             // pack voltage (V)
  current: number             // pack current (A)
  power:   number             // pack power (W) — positive = charging, negative = discharging
  chargingState: ChargingState  // "charging" | "discharging" | "standby"

  // Energy
  remainingKwh:   number      // estimated remaining energy (kWh)
  capacityAh:     number      // rated capacity (Ah)
  ratedEnergyKwh: number | null  // rated energy (kWh) from BMS — null if not reported

  // Cell voltages (16 cells, mV)
  cellVoltages:   number[]
  cellVoltageMin: number | null
  cellVoltageMax: number | null
  cellDelta:      number | null  // spread max−min (mV) — primary imbalance indicator
  minCellNum:     number | null  // 1-based index of weakest cell
  maxCellNum:     number | null  // 1-based index of strongest cell

  // Temperature (°C) — 4 physical sensors; 3276.7 °C sentinel filtered out
  cellTemps: number[]
  tempMin:   number
  tempMax:   number

  // Module breakdown (4 modules × 4 cells)
  modules: BatteryModule[]

  // BMS protection limits
  chargeVoltLimit:    number | null  // max charge voltage (V)
  dischargeVoltLimit: number | null  // min discharge voltage (V)
  chargeCurrLimit:    number | null  // max charge current (A)
  dischargeCurrLimit: number | null  // max discharge current (A)

  // BMS lifecycle counters
  batCycleIndex:        number | null  // total charge cycles
  batFullCount:         number | null  // times reached full charge
  batUnderVoltageCount: number | null  // under-voltage events
  warningCount:         number

  // Metadata
  isBalancing:   boolean        // bit 6 of bmsState — BMS actively balancing cells
  bmsState:      number | null  // raw BMS state register
  dataTime:      string | null  // ISO timestamp of last Felicity API report
  reportFreqSec: number | null  // reporting interval (s)
  wifiSignal:    number         // dBm
}

BatteryModule

One of the 4 modules inside a pack (each has 4 cells).

interface BatteryModule {
  index: number    // 1–4
  cells: number[]  // 4 cell voltages (mV)
  temp:  number | null  // physical sensor for this module (°C)
  min:   number    // lowest cell in this module (mV)
  max:   number    // highest cell in this module (mV)
  delta: number    // max − min spread within this module (mV)
}

BatteriesResult

Returned by client.getBatteries().

interface BatteriesResult {
  batteries: Battery[]
  fetchedAt: string                      // ISO timestamp of the fetch
  fromCache: boolean
  trend:     Record<string, BalanceTrend>  // keyed by serial number
}

BatteryResult

Returned by client.getBattery(id).

interface BatteryResult {
  battery:   Battery | null  // null when id not found
  fetchedAt: string
  fromCache: boolean
}

BatteryHealth

Returned per battery by computeHealth(batteries, snapshots). Keyed by serial number.

interface BatteryHealth {
  alias:           string
  cellDeltaStatus: "ok" | "warn" | "crit" | null  // null when cellDelta unavailable
  cellDelta:       number | null  // live spread (mV)
  dischargeDelta:  number | null  // median spread during discharge snapshots (mV) — more reliable than live
  tempStatus:      "ok" | "warn" | "crit" | null
  tempMax:         number | null
  sohStatus:       "ok" | "warn" | null  // SOH never reaches "crit"
  soh:             number | null
  outliers:        number[]    // 1-based cell indices persistently below pack average
  avgCRate:        number | null  // average C-rate over last ~6 snapshots
}

AutonomyResult

Returned by computeAutonomy(batteries, snapshots, opts).

interface AutonomyResult {
  totalRemainingKwh:     number       // sum of remainingKwh across all batteries
  totalCapacityKwh:      number       // sum of rated (or back-calculated) capacity
  dischargeRateKw:       number       // fleet rate used for all estimates
  estimatedHours:        number       // hours until fleet hits minSocPct
  estimatedHoursToFull:  number | null  // hours until fully charged; null if not charging
  estimatedSocAtSunrise: number | null  // % SOC at next sunrise; null if sunriseAt not given
  hoursToSunrise:        number | null
  estimatedDischargeKwh: number | null  // kWh discharged between now and sunrise
  estimatedRemainingKwh: number | null  // kWh remaining at sunrise
  perBattery:            AutonomyPerBattery[]
}

interface AutonomyPerBattery {
  sn:                   string
  alias:                string
  remainingKwh:         number
  estimatedHours:       number
  estimatedHoursToFull: number | null
}

interface AutonomyOptions {
  sunriseAt?:          string | Date | null  // ISO string or Date — enables sunrise fields
  packCapacityKwh?:    number | null         // explicit override; otherwise derived from BMS
  minSocPct?:          number                // reserve floor (default 5)
  defaultDischargeKw?: number                // fallback when no history (default 1.5)
}

BalanceTrend

Returned by snapshotStore.getTrend(sn) and snapshotStore.getAllTrends(batteries).

interface BalanceTrend {
  direction:              "improving" | "stable" | "degrading"
  deltaChange:            number    // mV change newest − oldest (negative = improving)
  history:                number[]  // cellDelta values oldest → newest
  balancingCount:         number    // snapshots where isBalancing = true
  snapshotCount:          number
  currentBalancingStreak: number    // consecutive trailing snapshots with balancing on
}

BatterySnapshot

One entry in the snapshot store — written every FELICITY_SNAPSHOT_MS (default 10 min).

interface BatterySnapshot {
  ts:        string  // ISO timestamp
  batteries: Array<{
    sn:          string
    alias:       string
    soc:         number
    soh:         number
    power:       number
    cellDelta:   number | null
    cellMin:     number | null
    cellMax:     number | null
    maxCellNum:  number | null
    minCellNum:  number | null
    voltages:    number[]
    temps:       number[]
    tempMax:     number
    tempMin:     number
    isBalancing: boolean
    warningCount:   number
    batCycleIndex:  number | null
  }>
}

MaterializedState

Returned by readState() — pre-computed state written by the poller on every tick. Zero-latency read; no recomputation needed.

interface MaterializedState {
  updatedAt: string                        // ISO timestamp of last poller tick
  batteries: Battery[]
  health:    Record<string, BatteryHealth>
  trend:     Record<string, BalanceTrend>
  autonomy:  AutonomyResult
}

SnapshotPayload

Emitted by snapshotEmitter and delivered to snapshot webhook subscribers.

interface SnapshotPayload {
  batteries: Battery[]
  health:    Record<string, BatteryHealth>
  ts:        string  // ISO emission timestamp
}

Alert

Returned as an array by computeAlerts(batteries, health) and by GET /alerts.

interface Alert {
  severity: "crit" | "warn" | "info"
  battery:  string           // alias
  code:     string           // machine-readable key e.g. "cell_delta_crit"
  message:  string           // human-readable description
}

const AlertSeverity = { CRIT: "crit", WARN: "warn", INFO: "info" } as const

EnergyDay

One day's energy totals — returned by computeEnergyHistory(snapshots) and GET /energy.

interface EnergyDay {
  date:            string  // "YYYY-MM-DD"
  kwhCharged:      number
  kwhDischarged:   number
  kwhNet:          number  // charged − discharged (positive = net import)
  peakChargeKw:    number
  peakDischargeKw: number
  snapshotCount:   number
}

DailyEnergyStore

Persistent 90-day energy accumulator — singleton exported as dailyEnergyStore.

class DailyEnergyStore {
  update(entries: DailyEnergy[]): void  // merge new entries; old days are never overwritten
  get(): DailyEnergy[]                  // sorted by date ascending
}

CellStat / PowerStats

Returned by computeCellStats(snapshots, sn) and computePowerStats(snapshots, batteries).

interface CellStat {
  cell:          number   // 1-based index
  module:        number   // 1-based module number
  mean:          number   // average voltage (mV)
  stddev:        number   // standard deviation (mV)
  min:           number
  max:           number
  meanDeviation: number   // mean − pack average (mV)
  trend:         "improving" | "stable" | "degrading"
}

interface PowerStats {
  totalSamples:      number
  chargeSamples:     number
  dischargeSamples:  number
  peakChargeKw:      number
  avgChargeKw:       number
  peakDischargeKw:   number
  avgDischargeKw:    number
  avgCRate:          number | null   // null when no ratedEnergyKwh available
  pctAboveHalfC:     number | null
}

Enums

All discriminant strings are exported as frozen const objects — use them instead of bare strings for autocomplete and compile-time safety.

import { ChargingState, HealthStatus, TrendDirection, HookEvent } from 'fsolar-mcp'

// ChargingState
ChargingState.CHARGING    // "charging"
ChargingState.DISCHARGING // "discharging"
ChargingState.STANDBY     // "standby"

// HealthStatus
HealthStatus.OK    // "ok"
HealthStatus.WARN  // "warn"
HealthStatus.CRIT  // "crit"

// TrendDirection
TrendDirection.IMPROVING  // "improving"
TrendDirection.STABLE     // "stable"
TrendDirection.DEGRADING  // "degrading"

// HookEvent
HookEvent.CELL_DELTA_CRIT     // "cell_delta_crit"
HookEvent.CELL_DELTA_WARN     // "cell_delta_warn"
HookEvent.TEMP_CRIT           // "temp_crit"
HookEvent.TEMP_WARN           // "temp_warn"
HookEvent.SOH_WARN            // "soh_warn"
HookEvent.LOW_SOC             // "low_soc"
HookEvent.FULL                // "full"
HookEvent.ONLINE              // "online"
HookEvent.OFFLINE             // "offline"
HookEvent.OUTLIER             // "outlier"
HookEvent.BMS_WARNINGS        // "bms_warnings"
HookEvent.UNDERVOLTAGE_EVENTS // "undervoltage_events"
HookEvent.STALE_DATA          // "stale_data"
HookEvent.ALERT               // "alert"  — fleet catch-all
HookEvent.SNAPSHOT            // "snapshot"

Types match their string values — battery.chargingState === ChargingState.CHARGING compiles and narrows correctly.

Event-driven: webhooks & emitter

React to battery state changes without polling. Two delivery mechanisms — use one or both.

HTTP webhooks

Register a URL to receive POST requests when events fire:

POST /hooks         body: { url, events? }   # register
GET  /hooks         # list registered hooks
DELETE /hooks/:id   # remove a hook

# receive all events
curl -X POST http://localhost:3010/hooks \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://your-server.com/webhook"}'

# receive only critical cell alerts and periodic snapshots
curl -X POST http://localhost:3010/hooks \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://your-server.com/webhook", "events": ["cell_delta_crit", "snapshot"]}'

Real-time SSE stream

Connect any browser or HTTP client to GET /events for a live push feed:

const es = new EventSource('http://localhost:3010/events', {
  headers: { 'X-API-Key': 'your-key' }
})
es.addEventListener('state',    (e) => console.log('initial:', JSON.parse(e.data)))
es.addEventListener('snapshot', (e) => console.log('tick:',    JSON.parse(e.data)))

• event: state — sent once on connect with the last persisted MaterializedState
• event: snapshot — sent every poll tick (~30 s) with { batteries, health, ts }
• Reconnects automatically using retry: 5000 in the stream header

EventEmitter (same-process)

Subscribe directly in Node.js without an HTTP round-trip:

import { startPoller, snapshotEmitter } from 'fsolar-mcp'

snapshotEmitter.on('snapshot', ({ batteries, health, ts }) => {
  // fires every poll tick (~30 s by default)
  console.log(batteries[0].soc, health)
})

startPoller(client)

The startPoller onTick callback is useful for integrating poll errors into a larger application:

startPoller(client, {
  onTick: (err, batteries) => {
    if (err) myMonitoring.recordError(err)
    else     myMonitoring.recordSuccess(batteries!.length)
  },
})

Hook events

| Event | Trigger | Payload extras | Cooldown | |---|---|---|---| | cell_delta_crit | Cell delta ≥ 200 mV | sn, alias, value, threshold | 1 h | | cell_delta_warn | Cell delta ≥ 120 mV | sn, alias, value, threshold | 4 h | | temp_crit | tempMax ≥ 50 °C | sn, alias, value, threshold | 1 h | | temp_warn | tempMax ≥ 40 °C | sn, alias, value, threshold | 4 h | | soh_warn | SOH < 90 % | sn, alias, value, threshold | 24 h | | low_soc | SOC ≤ FELICITY_LOW_SOC_PCT % (default 20) | sn, alias, value, threshold | 2 h | | full | SOC = 100 % + standby | sn, alias | 8 h | | online | Battery appears after absence | sn, alias | 1 h | | offline | Battery disappears | sn, alias | 1 h | | outlier | Persistent outlier cells detected | sn, alias | 24 h | | bms_warnings | BMS active warning count > 0 | sn, alias | 4 h | | undervoltage_events | Cumulative under-voltage counter > 0 | sn, alias | 24 h | | stale_data | Last BMS report > 30 min old | sn, alias | 2 h | | alert | Fleet catch-all — any alert active or new alerts appeared | alerts[], newAlerts[], count, newCount | 1 h (bypassed for new alerts) | | snapshot | Time-based (every FELICITY_TELEMETRY_MS, default 5 min) | full SnapshotPayload | none |

Thresholds match computeHealth constants (HEALTH_CELL_DELTA_CRIT, HEALTH_TEMP_WARN, etc. — see docs/ALGORITHMS.md).

The alert event is diff-based: it fires immediately when a new alert code appears (bypassing the 1 h cooldown), and then on the cooldown schedule while the same alerts persist. The newAlerts[] field contains only the newly-appeared alerts since the last tick; alerts[] is the full current list.

Configuration

| Variable | Required | Default | Description | |---|---|---|---| | FELICITY_USER | Yes | — | Felicity Solar account email | | FELICITY_PASS | Yes | — | Felicity Solar account password | | FELICITY_PORT | No | 3010 | HTTP server port | | FELICITY_API_KEY | No | — | If set, all REST + MCP SSE requests must supply Authorization: Bearer <key> or X-API-Key: <key> | | FELICITY_CORS_ORIGIN | No | localhost origins only | Allowed CORS origin. Set to * to open fully, or an explicit origin to lock down | | FELICITY_RATE_LIMIT | No | 60 | Max REST requests per minute per IP. Set to 0 to disable | | FELICITY_POLL_MS | No | 30000 | Felicity API poll interval (ms) | | FELICITY_TOKEN_TTL_H | No | 6 | Felicity auth token lifetime in hours before proactive refresh | | FELICITY_LOW_SOC_PCT | No | 20 | SOC % threshold that triggers the low_soc webhook event | | FELICITY_TARIFF_KWH | No | — | Electricity tariff in currency/kWh used by the get_cost_savings MCP tool | | FELICITY_TELEMETRY_MS | No | 300000 | Snapshot emitter / webhook interval (ms) | | FELICITY_SNAPSHOT_ENABLED | No | true | Enable background snapshot store | | FELICITY_SNAPSHOT_MS | No | 600000 | Snapshot store interval (ms, min 60 000) | | FELICITY_SNAPSHOT_DAYS | No | 3 | Intra-day snapshot retention (days) | | FELICITY_DAILY_DAYS | No | 90 | Daily snapshot retention (days) | | SNAPSHOT_DIR | No | os.tmpdir() | Directory for all persisted JSON files: battery-snapshots.json, battery-daily.json, battery-state.json, battery-energy.json, battery-hooks.json, battery-hook-cooldowns.json, battery-hook-retries.json |

What you can build

Real-time fleet view — per-cell voltages, SOC, power flow, SOH, balancing state and temperature for every battery in the pack.

Cell-level inspection — voltage, deviation from pack average, module spread, LiFePO4 charge %, weakest/strongest cell.

Historical trends — cell-delta and temperature over the last 24 h, per-cell deviation heatmap, daily SOH trend, lifetime cycle-count with projected remaining battery life.

Discharging view — live power flow and SOC during active discharge across the fleet.

Algorithms & metrics

Formulas, thresholds, hook event conditions, and snapshot behaviour: docs/ALGORITHMS.md.

How it works

The Felicity cloud API requires passwords to be RSA-encrypted (public key extracted from the Android APK). The client handles login, token refresh, and caching automatically. A background poller keeps data fresh so MCP tool calls and REST requests are instant.

Setup from source

git clone https://github.com/RicardoSantos/mcp-fsolar
cd mcp-fsolar
npm install
npm run build          # compile TypeScript → dist/
cp .env.example .env   # fill in your credentials
node dist/server.js

node probe.js          # dump raw API responses for every device

License

MIT