⚡ 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.

License

MIT © Zukanye Ndiki