⚡ 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

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.

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

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

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