⚡ 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

Prerequisites

Node.js 18+
An EskomSePush API token from eskomsepush.gumroad.com/l/api

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

Option 1 — npx (recommended)

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.

eskomsepush-mcp