eskomsepush-mcp
Integrates with EskomSePush's Gumroad API token system, allowing users to obtain and use API tokens for accessing load shedding data through tiered subscription plans.
Connects to the EskomSePush developer community on ZATech Slack, providing access to community support and collaboration channels for developers using the load shedding API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@eskomsepush-mcp what's the current load shedding stage?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
⚡ 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 |
| Current national load shedding stage (Eskom + Cape Town) | Free ✅ |
| See how many API calls you have left today | Free ✅ |
| Find your area ID by suburb or city name | Paid 💳 |
| Upcoming events and full schedule for your area | Paid 💳 |
| 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
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 |
|
Paid | From $55/yr | All 5 tools |
Installation
Option 1 — npx (recommended)
npx eskomsepush-mcpOption 2 — Clone & build
git clone https://github.com/zukhanyendiki9-code/eskomsepush-mcp.git
cd eskomsepush-mcp
npm install
npm run buildConfiguration
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-mcpCursor / 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 testingTip: Pass
test: trueto any tool during development — it returns mock data and doesn't count against your daily quota.
Testing status
Tool | Tested on free plan |
| ✅ |
| ✅ |
| ⚠️ Requires paid plan |
| ⚠️ Requires paid plan |
| ⚠️ 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 toolscheck_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
Scored across 5 tools
Each tool serves a distinct purpose: API allowance, area schedule, nearby areas, national status, and area search. No overlap in functionality.
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.
Five tools is well-scoped for the EskomSePush API domain, covering the essential operations without feeling thin or overloaded.
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
Related MCP Connectors
Paid Electricity Market & Grid Intelligence API via x402. Unpaid tool calls return 402.
Real-time electricity price signals for AI agents. Spot prices, cheapest hours, and contract recommendations. 31 countries across Europe and Oceania. No authentication required.
Unofficial GridStatus MCP — wraps the GridStatus.io REST API (api.gridstatus.io/v1)
Paid Solar, Battery & Distributed Energy Intelligence API via x402. Unpaid tool calls return 402.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides 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-
- AlicenseAqualityDmaintenanceProvides 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.9MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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
- AlicenseNot gradedqualityFmaintenanceEnables 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 npmMIT