@tidegap/mcp
v0.21.0
Published
MCP server: run non-urgent LLM tasks at the cleanest grid hour before a deadline, via Batch APIs when allowed.
Readme
@tidegap/mcp
Renamed from
@ebb-ai/mcpin 0.18.0. Use the host config keytidegapandnpx -y @tidegap/mcp; theebb-mcpbin and theEBB_*variables were removed in 0.19. See Renamed from Ebb AI.
MCP server that lets your agent run non-urgent LLM tasks at the cleanest grid hour before a deadline.
Add it to any MCP host. When a user says "do this tonight" or "by tomorrow", the agent calls schedule_task. Tidegap then runs the task at the lowest-carbon grid hour before the deadline, and through the provider Batch API when the deadline allows.
- 12 MCP tools (measured), among them
recommend_window,schedule_task,check_queue_status,get_grid_forecast,cancel_task,postpone_task,update_deadline. - Live 72-hour forecast. GB needs no key; other regions use free keys (EIA, ENTSO-E, WattTime, Electricity Maps).
- One signed carbon receipt per task, stored in
~/.tidegap/queue.db.
npx -y @tidegap/mcp{ "mcpServers": {
"tidegap": { "command": "npx", "args": ["-y", "@tidegap/mcp"] }
} }Proof: one real GB run, 2026-09-30. Forecast peak 183 gCO2/kWh vs recommended window 88 gCO2/kWh, about 52 % lower for this run only (forecast, projected). Receipt at dispatch: 158 gCO2/kWh (measured). Host-specific configs: https://www.tidegap.com/docs#install
Run
npx -y @tidegap/mcpThe server speaks MCP over stdio. To wire it into an agent client:
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json
on macOS (Linux/Windows have similar paths):
{
"mcpServers": {
"tidegap": {
"command": "npx",
"args": ["-y", "@tidegap/mcp"],
"env": {
"TIDEGAP_ELECTRICITY_MAPS_API_KEY": "optional - mock data without it",
"TIDEGAP_DEFAULT_REGION": "US-CAL-CISO"
}
}
}
}Restart Claude Desktop after editing.
Claude Code
Add tidegap to your ~/.claude/mcp.json (or workspace .claude/mcp.json):
{
"mcpServers": {
"tidegap": {
"command": "npx",
"args": ["-y", "@tidegap/mcp"]
}
}
}OpenClaw
Add to ~/.openclaw/mcp.json:
{
"mcpServers": {
"tidegap": {
"command": "npx",
"args": ["-y", "@tidegap/mcp"]
}
}
}Tools exposed (12, measured)
| Tool | Purpose |
|---|---|
| schedule_task(... repeat?, every_hours?, days?, window?, time_zone?) with repeat daily, weekdays, weekly or every_n_hours | Create a recurring job: each run is a new task at the cleanest hour of its period. End it with cancel_task(series: true). |
| get_grid_forecast(region, hours?) | Hour-by-hour carbon intensity for a region; useful before deciding whether to defer. |
| recommend_window(deadline, region?, ...) | Plan the cleanest window inside the deadline without queueing anything. |
| schedule_task(prompt, deadline, model?, region?, carbon_budget_g?, repeat?, origin_session_id?, not_before?) | Queue a task to run in the cleanest window inside the deadline. Returns a task_id and one line that says whether it will run: Runs at <time> local., or the readiness sentence with its fix, for example Tasks will not run: no tick daemon. Run `tidegap install`.. not_before sets the earliest start. repeat defaults to none, also for deadline_kind: "quota_reset". |
| schedule_task(... llm_timeout?) | The run's time limit, or each job run's: a duration from 1s to 7d (45m, 2h) or none; 0 is refused. Without it the user's setting (tidegap limits) or the built-in default applies. check_queue_status with a task_id prints time_limits: with each source. See Run limits. |
| schedule_task(... retries?, retry_delay?) | How a failed run is tried again: retries 0 to 10 (0 runs it once), retry_delay a duration that doubles for each later retry. Without them the user's setting or one retry after 30 minutes applies; a permanent failure never retries, and only the final outcome notifies. check_queue_status prints retries: and one attempt_<n>: line per failed attempt. See Retries. |
| schedule_task(... runner?, cwd?, permission_profile?, result_path?, wake_session?) | Hand off the work shape: runner is another name for provider; cwd is the folder a claude-code run works in (another folder than the session's runs fresh there); permission_profile is read, web or none (read with a cwd); result_path is a new file Tidegap writes the result text to, inside cwd, the session's project folder or the temp folder. wake_session: true wakes the idle Claude Code session that queued the task when it finishes (within 12 hours after its last turn; refused outside a session). runner or provider command is refused with the tidegap queue add --runner command line. output_path follows the same folder rules. |
| check_queue_status(task_id?) | Inspect the queue or one specific task; includes a carbon receipt once the task has completed. |
| cancel_task(task_id, series?) | Cancel a queued or scheduled task; on a repeating task, skip it, or end the series with series: true. |
| reply_task(task_id, text, deadline?) | Continue a completed task: a new task with the conversation plus this text, same provider and model. |
| expedite_task(task_id) | Dispatch a queued or scheduled task now, outside its carbon window. |
| postpone_task(task_id, preset? \| until? \| delay_minutes?, reset_at?) | "Later": move a pending task later, never earlier. Presets 1h, tonight (22:00 to 06:00), tomorrow_morning (09:00 to 12:00), after_limit_reset (5 minutes after the Claude limit reset: reset_at, else this machine's limit reading, else a reset time given before). |
| update_deadline(task_id, deadline) | Reschedule a task against a new deadline. |
| retry_task(task_id) | Run a failed task again as attempt 1 of a new count: now with the provider's key in the server env; a command or claude-code task, or one without a key here, on the next tidegap tick. |
| cancel_all(status?) | Cancel every task that is still queued or scheduled. |
| tidegap_usage(include_spend?) | Read-only: the Claude Code subscription limits of this machine and when they reset, and the Codex limits from its local logs. include_spend adds the current 5-hour window's tokens and an API list-price cost estimate. |
Environment variables
These variables configure this MCP server (and the tidegap CLI, which reads
the same set). They are read at the server's own entry point and injected into
@tidegap/core, which is environment-pure and reads nothing ambient itself.
OpenClaw plugin users: the
@vitalini/tidegapOpenClaw plugin reads no environment variables. Configure it through plugin config instead, underplugins.entries.tidegap.configin your gateway config — the "Plugin config" column below names the field that replaces each variable. OpenClaw resolves the"${ENV_VAR}"shorthand in those fields, so you can keep exporting the same variables and let the gateway read them on the plugin's behalf.
| Var | Plugin config | Purpose |
|---|---|---|
| TIDEGAP_ELECTRICITY_MAPS_API_KEY | electricityMapsApiKey | API key from electricitymaps.com. Universal fallback. If unset (and no zone-specific feed is configured), the server falls back to deterministic mock data so you can still run the whole stack locally. |
| TIDEGAP_EIA_API_KEY | eiaApiKey | Free US EIA key. Enables average-emissions intensity for the US ISO zones (CAISO / ERCOT / ISO-NE / NYISO / PJM / MISO). |
| TIDEGAP_ENTSOE_SECURITY_TOKEN | entsoeSecurityToken | Free ENTSO-E token. Enables EU zone intensity (FR / DE / ES / IT / NL). |
| WATTTIME_USERNAME + WATTTIME_PASSWORD | wattTimeUsername + wattTimePassword | Free WattTime v3 account. Enables marginal-emissions (co2_moer) forecasts for the US ISO zones — takes precedence over EIA where covered, falls through to EIA on any error. The marginal signal is disclosed as signalType: "marginal" on forecasts and receipts. |
| TIDEGAP_DEFAULT_REGION | defaultRegion | Region when a tool call names none. Beats the stored region setting; see Grid region. |
| ANTHROPIC_API_KEY | anthropicApiKey | Enables the anthropic provider (batch-capable). |
| OPENAI_API_KEY | openaiApiKey | Enables the openai provider (batch-capable). |
| GEMINI_API_KEY / GOOGLE_API_KEY | geminiApiKey / googleApiKey | Enables the gemini provider (Generative Language API, sync-only). GEMINI_API_KEY is preferred; GOOGLE_API_KEY is the fallback. |
| OLLAMA_HOST | ollamaHost | Enables the local ollama provider (sync-only). Default http://localhost:11434; keyless — set this var to opt the provider in. |
Grid region
The server resolves the region of each tool call in this order:
- the tool call's
regionargument, TIDEGAP_DEFAULT_REGIONin the server's environment (the agent host's MCP config),- the region setting stored on this machine:
tidegap region set <zone>, or Settings → Grid region intidegap uiand the Mac app (keyTIDEGAP_DEFAULT_REGIONin~/.tidegap/config), - a guess from the machine's time zone,
GB.
The server reads the setting again when the file changes, so a new setting applies on the next tool call with no restart. A stored value that is not a supported zone is ignored, with one stderr warning per change. schedule_task replies carry region_source: flag | env | setting | timezone | fallback.
A region argument must be one of the 31 supported zones (any case). Another value is rejected with the closest zones and a link to request a region, for example Unknown zone UA. Closest: PL. Request a region: <link>. With TIDEGAP_ELECTRICITY_MAPS_API_KEY set, any zone passes, because Electricity Maps serves zones beyond the list; with TIDEGAP_ENTSOE_SECURITY_TOKEN set, IT passes too.
Develop
From the root of a clone of https://github.com/tidegap/tidegap:
pnpm install
pnpm --filter @tidegap/mcp build
node packages/mcp-server/dist/server.js