Skip to main content
Glama

⚡ eskomsepush-mcp

Model Context Protocol server for EskomSePush — bringing real-time South African load shedding data to Claude and any MCP-compatible AI client.

Built by a South African developer, for South Africans. Ask Claude about load shedding in plain language.


What it does

Tool

Description

Plan

get_status

Current national load shedding stage (Eskom + Cape Town)

Free ✅

check_allowance

See how many API calls you have left today

Free ✅

search_areas

Find your area ID by suburb or city name

Paid 💳

get_area_schedule

Upcoming events and full schedule for your area

Paid 💳

get_areas_nearby

Discover areas by GPS coordinates

Paid 💳

Example prompts

  • "What stage are we on right now?" → works on free plan

  • "How many API calls do I have left today?" → works on free plan

  • "Is there load shedding in Stellenbosch tonight?" → paid plan

  • "Show me the load shedding schedule for Sandton this week" → paid plan

  • "Find load shedding areas near me" (with GPS) → paid plan


Related MCP server: Energy Grid MCP Server

Prerequisites

API Plan Requirements

EskomSePush operates a tiered API. The free tier returns HTTP 410 Gone on area-lookup endpoints — those require a paid subscription. This MCP server exposes the full tool surface regardless of plan; unsupported tools will surface the 410 as a clear error to the client.

Plan

Cost

What works

Free

$0 via Gumroad

get_status, check_allowance

Paid

From $55/yr

All 5 tools


Installation

npx eskomsepush-mcp

Option 2 — Clone & build

git clone https://github.com/zukhanyendiki9-code/eskomsepush-mcp.git
cd eskomsepush-mcp
npm install
npm run build

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

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

{
  "mcpServers": {
    "eskomsepush": {
      "command": "npx",
      "args": ["-y", "eskomsepush-mcp"],
      "env": {
        "ESP_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Claude Code

claude mcp add eskomsepush -e ESP_API_TOKEN=your-token -- npx -y eskomsepush-mcp

Cursor / Windsurf

{
  "mcpServers": {
    "eskomsepush": {
      "command": "npx",
      "args": ["-y", "eskomsepush-mcp"],
      "env": {
        "ESP_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Development

npm run build        # compile TypeScript
npm run dev          # watch mode
npm run inspect      # open MCP Inspector UI for testing

Tip: Pass test: true to any tool during development — it returns mock data and doesn't count against your daily quota.

Testing status

Tool

Tested on free plan

get_status

✅

check_allowance

✅

search_areas

⚠️ Requires paid plan

get_area_schedule

⚠️ Requires paid plan

get_areas_nearby

⚠️ Requires paid plan

If you're on a paid plan and test any of the paid-tier tools, please open an issue or PR to confirm behaviour.


API Quota

Plan

Calls/day

Free

50

Paid

Higher limits

Use the check_allowance tool to monitor your usage. Use test: true while building.


Contributing

PRs welcome. If you're South African and have ideas for making this more useful, open an issue.

Join the EskomSePush developer community on ZATech Slack in #eskomsepush.


License

MIT © Zukanye Ndiki

Available Tools

5 tools
check_allowanceA

Check how many EskomSePush API calls you have remaining today. Free tier allows 50 calls per day.

Inputs: no named parameters.

get_area_scheduleA

Get the upcoming load shedding schedule and events for a specific area. Requires an area ID — use search_areas first if you don't have one.

Inputs: area_id (required), test.

get_areas_nearbyA

Find load shedding areas near a GPS location. Useful when you know coordinates but not the area name.

Inputs: lat (required), lon (required), test.

get_statusB

Get the current national load shedding stage for both Eskom and Cape Town. Use this to find out what stage we are on right now.

Inputs: test.

search_areasA

Search for load shedding areas by name or suburb. Returns area IDs you can use with get_area_schedule. Always search first if you don't have an area ID.

Inputs: text (required), test.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool serves a distinct purpose: API allowance, area schedule, nearby areas, national status, and area search. No overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (check_allowance, get_area_schedule, get_areas_nearby, get_status, search_areas), using snake_case throughout.

    Tool Count5/5

    Five tools is well-scoped for the EskomSePush API domain, covering the essential operations without feeling thin or overloaded.

    Completeness5/5

    The tool set covers all core functionality of the EskomSePush API: status, area lookup, schedule, nearby search, and API quota checking. No obvious gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides real-time access to Israeli emergency alerts from the official Pikud Haoref (Home Front Command) API. Enables AI assistants to check current alerts, retrieve alert history with intelligent city filtering, and monitor emergency notifications including rocket alerts, aerial intrusions, and earthquakes.
      5
      -
    • A
      license
      A
      quality
      D
      maintenance
      Provides real-time electricity grid data including CO2 intensity, power mix, and wholesale prices, plus optimal green time windows for energy-intensive AI tasks. Supports UK, Germany, and global regions with optional API keys.
      9
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to access and analyze Spanish electricity consumption data via the Datadis API, providing tools for supply management, consumption analysis, anomaly detection, and executive reporting.
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables querying of real-time and forecast UK carbon intensity data from National Grid ESO, allowing AI agents to retrieve carbon emissions by region and time.
      3 npm
      MIT