Skip to content
MCP server

ebb-ai

MCP server that queues non-urgent LLM tasks for the cleanest electricity grid hour

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, self-hosted
Runs
Locally
Version
0.17.0
Listing updated
2 days ago

About ebb-ai

ebb-ai is an open-source MCP server for ai models and llm tooling. It runs locally on your machine and is started by your AI client.

Registered as ebb-ai, this server has since been renamed Tidegap in version 0.18, with the npm package now @tidegap/mcp. The idea is that when a user says to do something tonight or by tomorrow, the agent calls schedule_task, and the task runs in the lowest-carbon hour before the deadline, through the provider's Batch API when time allows.

It reads a live 72-hour grid forecast. Great Britain needs no key, and other regions use free keys from EIA, ENTSO-E, WattTime or Electricity Maps. Each task gets one signed carbon receipt stored in a local SQLite queue. The README gives one real GB run in which the forecast peak was 183 gCO2/kWh against 88 in the chosen window, calling the roughly 52 percent saving a projection for that run only, with 158 measured at dispatch.

Queued tasks run through a small local daemon, and recurring jobs can be set daily, weekdays, weekly or every N hours. It dispatches to Anthropic or OpenAI with your own keys and is Apache-2.0 open source. Twelve tools are exposed, and there are TypeScript and Python libraries for the same scheduler.

Install

Run in a terminal

claude mcp add ebb-ai --env ANTHROPIC_API_KEY='<ANTHROPIC_API_KEY>' --env OPENAI_API_KEY='<OPENAI_API_KEY>' --env EBB_EIA_API_KEY='<EBB_EIA_API_KEY>' --env EBB_ENTSOE_SECURITY_TOKEN='<EBB_ENTSOE_SECURITY_TOKEN>' --env WATTTIME_PASSWORD='<WATTTIME_PASSWORD>' --env EBB_ELECTRICITY_MAPS_API_KEY='<EBB_ELECTRICITY_MAPS_API_KEY>' -- npx -y @ebb-ai/mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "ebb-ai": {
      "command": "npx",
      "args": [
        "-y",
        "@ebb-ai/mcp"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>",
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "EBB_EIA_API_KEY": "<EBB_EIA_API_KEY>",
        "EBB_ENTSOE_SECURITY_TOKEN": "<EBB_ENTSOE_SECURITY_TOKEN>",
        "WATTTIME_PASSWORD": "<WATTTIME_PASSWORD>",
        "EBB_ELECTRICITY_MAPS_API_KEY": "<EBB_ELECTRICITY_MAPS_API_KEY>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "ebb-ai": {
      "command": "npx",
      "args": [
        "-y",
        "@ebb-ai/mcp"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>",
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "EBB_EIA_API_KEY": "<EBB_EIA_API_KEY>",
        "EBB_ENTSOE_SECURITY_TOKEN": "<EBB_ENTSOE_SECURITY_TOKEN>",
        "WATTTIME_PASSWORD": "<WATTTIME_PASSWORD>",
        "EBB_ELECTRICITY_MAPS_API_KEY": "<EBB_ELECTRICITY_MAPS_API_KEY>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "ebb-ai": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@ebb-ai/mcp"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>",
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "EBB_EIA_API_KEY": "<EBB_EIA_API_KEY>",
        "EBB_ENTSOE_SECURITY_TOKEN": "<EBB_ENTSOE_SECURITY_TOKEN>",
        "WATTTIME_PASSWORD": "<WATTTIME_PASSWORD>",
        "EBB_ELECTRICITY_MAPS_API_KEY": "<EBB_ELECTRICITY_MAPS_API_KEY>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "ebb-ai": {
      "command": "npx",
      "args": [
        "-y",
        "@ebb-ai/mcp"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>",
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "EBB_EIA_API_KEY": "<EBB_EIA_API_KEY>",
        "EBB_ENTSOE_SECURITY_TOKEN": "<EBB_ENTSOE_SECURITY_TOKEN>",
        "WATTTIME_PASSWORD": "<WATTTIME_PASSWORD>",
        "EBB_ELECTRICITY_MAPS_API_KEY": "<EBB_ELECTRICITY_MAPS_API_KEY>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "ebb-ai": {
      "command": "npx",
      "args": [
        "-y",
        "@ebb-ai/mcp"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>",
        "OPENAI_API_KEY": "<OPENAI_API_KEY>",
        "EBB_EIA_API_KEY": "<EBB_EIA_API_KEY>",
        "EBB_ENTSOE_SECURITY_TOKEN": "<EBB_ENTSOE_SECURITY_TOKEN>",
        "WATTTIME_PASSWORD": "<WATTTIME_PASSWORD>",
        "EBB_ELECTRICITY_MAPS_API_KEY": "<EBB_ELECTRICITY_MAPS_API_KEY>"
      }
    }
  }
}

Configuration

  • EBB_DEFAULT_REGIONDefault grid region, e.g. GB, US-CAL-CISO, DE
  • EBB_DB_PATHSQLite queue path (default ~/.ebb-ai/queue.db)
  • ANTHROPIC_API_KEYDispatch tasks to Anthropic (sync or Batch API)
  • OPENAI_API_KEYDispatch tasks to OpenAI (sync or Batch API)
  • EBB_EIA_API_KEYUS EIA grid data (CAISO, ERCOT, ISO-NE, PJM), free key
  • EBB_ENTSOE_SECURITY_TOKENENTSO-E grid data (EU regions), free token
  • WATTTIME_USERNAMEWattTime account (US marginal emissions)
  • WATTTIME_PASSWORDWattTime account password
  • EBB_ELECTRICITY_MAPS_API_KEYElectricity Maps fallback feed

Tools this server provides (7)

Taken from the project documentation; the running server may differ.

schedule_task
Queue a task to run in the cleanest window before a deadline, or set a recurring job.
recommend_window
Plan the cleanest window inside a deadline without queueing anything.
check_queue_status
Show the status of queued tasks.
get_grid_forecast
Hour-by-hour carbon intensity for a region.
cancel_task
Cancel a task or a series.
postpone_task
Postpone a queued task.
update_deadline
Change a task's deadline.

What it does

Carbon-aware scheduling
Runs a deferrable task at the lowest-carbon hour before its deadline.
Batch API dispatch
Uses provider batch endpoints when the deadline allows.
Grid forecast
72-hour carbon intensity for a region.
Carbon receipts
One signed receipt per task in a local queue.
Recurring jobs
Daily, weekday, weekly or every N hours schedules.
Queue controls
Postpone, cancel or change a deadline.

Good for

  • Defer a long summarisation until tomorrow morning
  • Run a nightly report at the cleanest hour
  • Check the grid forecast before deciding whether to wait
  • Keep a record of the carbon intensity at dispatch
  • Replace cron jobs with agent-scheduled tasks

Pricing

Open source

Apache-2.0; provider API usage billed by your own accounts

Prices change. Check ebb-ai.com before you buy.

ebb-ai FAQ

What licence is it under?

Apache-2.0.

Which grid regions work without a key?

Great Britain. Other regions use free keys from EIA, ENTSO-E, WattTime or Electricity Maps.

Which model providers can it dispatch to?

Anthropic and OpenAI using your own API keys.

What happened to the Ebb AI name?

It was renamed Tidegap in version 0.18.0 and the package is now @tidegap/mcp.

Is the carbon saving guaranteed?

No. The README says its example figure is a projection for one run only.

Is ebb-ai free?

Yes. ebb-ai is open source, so you can use and self-host it for free.

How do I add ebb-ai to Claude Code?

Run this command in your terminal: claude mcp add ebb-ai --env ANTHROPIC_API_KEY='<ANTHROPIC_API_KEY>' --env OPENAI_API_KEY='<OPENAI_API_KEY>' --env EBB_EIA_API_KEY='<EBB_EIA_API_KEY>' --env EBB_ENTSOE_SECURITY_TOKEN='<EBB_ENTSOE_SECURITY_TOKEN>' --env WATTTIME_PASSWORD='<WATTTIME_PASSWORD>' --env EBB_ELECTRICITY_MAPS_API_KEY='<EBB_ELECTRICITY_MAPS_API_KEY>' -- npx -y @ebb-ai/mcp

What are the best alternatives to ebb-ai?

The closest alternatives to ebb-ai are Ha MCP, Claude Code Ultimate Guide, Concord MCP, note1 and CalderFlow.

Alternatives to ebb-ai

  1. Ha MCP

    MCP server

    MCP server for managing and automating Home Assistant from AI assistants

    Runs locally
    • 8 tools
    • Open source
    • 7.9K GitHub stars
    • Productivity
  2. MCP server for searching the Claude Code Ultimate Guide from any MCP client

    Runs locally
    • Open source
    • 6.5K GitHub stars
    • AI models and LLM tooling
  3. Concord MCP

    MCP server

    Local-first MCP server for messaging and shared work-state between coding agents

    Runs locally
    • Freemium
    • 1.3K GitHub stars
    • Developer tools
  4. note1

    MCP server

    MCP server giving AI assistants search and summaries across your note1 meetings

    • 4 tools
    • Remote
    • Free trial
    • 1 GitHub star
    • Productivity
  5. CalderFlow

    MCP server

    Turn notes or specs into editable flowcharts, timelines and funnels from an AI assistant

    • 10 tools
    • Remote
    • Free
    • Design and media
  6. nicemails

    MCP server

    Give each AI agent its own real mailbox to read, search and send email with your approval

    • 8 tools
    • Remote
    • Freemium
    • Communication