ebb-ai — carbon-aware MCP scheduler

@tidegap/mcp

在 0.18.0 中从 @ebb-ai/mcp 更名。使用主机配置键 tidegap 和 npx -y @tidegap/mcp；ebb-mcp 可执行文件和 EBB_* 变量已在 0.19 中移除。请参阅更名自 Ebb AI。

MCP 服务，让你的 Agent 能在截止时间前，于电网碳强度最低的时段运行非紧急大模型任务。

将其添加到任意 MCP 主机。当用户说“今晚做这件事”或“明天之前完成”时，Agent 会调用 schedule_task。随后，Tidegap 会在截止时间前电网碳强度最低的时段运行任务；若截止时间允许，还会通过提供商的 Batch API 运行。

• 12 个 MCP 工具（实测），其中包括 recommend_window、schedule_task、check_queue_status、get_grid_forecast、cancel_task、postpone_task、update_deadline。
• 实时 72 小时预测。GB 无需密钥；其他地区可使用免费密钥（EIA、ENTSO-E、WattTime、Electricity Maps）。
• 每项任务都有一份签名碳排放凭证，存储在 ~/.tidegap/queue.db。

npx -y @tidegap/mcp

{ "mcpServers": {
    "tidegap": { "command": "npx", "args": ["-y", "@tidegap/mcp"] }
} }

实测证明：一次真实的 GB 运行，日期为 2026-09-30。预测峰值为 183 gCO2/kWh，推荐时段为 88 gCO2/kWh；仅本次运行的预测值降低约 52 %（预测，估算值）。调度时的凭证：158 gCO2/kWh（实测）。各主机专属配置：https://www.tidegap.com/docs#install

运行

npx -y @tidegap/mcp

该服务通过 stdio 使用 MCP。要将其接入 Agent 客户端：

Claude Desktop

在 macOS 上编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （Linux/Windows 的路径类似）：

{
  "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"
      }
    }
  }
}

编辑后重启 Claude Desktop。

Claude Code

将 tidegap 添加到 ~/.claude/mcp.json（或工作区的 .claude/mcp.json）：

{
  "mcpServers": {
    "tidegap": {
      "command": "npx",
      "args": ["-y", "@tidegap/mcp"]
    }
  }
}

OpenClaw

添加到 ~/.openclaw/mcp.json：

{
  "mcpServers": {
    "tidegap": {
      "command": "npx",
      "args": ["-y", "@tidegap/mcp"]
    }
  }
}

已公开的工具（12 个，实测）

工具	用途
get_grid_forecast(region, hours?)	查询某个地区逐小时的碳强度；可用于决定是否延后任务。
recommend_window(deadline, region?, ...)	规划截止时间内碳强度最低的时段，不会将任务加入队列。
schedule_task(prompt, deadline, model?, region?, carbon_budget_g?, repeat?, origin_session_id?, not_before?)	将任务加入队列，在截止时间内碳强度最低的时段运行。返回 task_id 和一行说明任务是否会运行的消息：Runs at <time> local.，或者包含解决方法的就绪状态提示，例如 Tasks will not run: no tick daemon. Run `tidegap install`.。not_before 设置最早开始时间。repeat 默认为 none，deadline_kind: "quota_reset" 时也如此。
check_queue_status(task_id?)	查看队列或某个特定任务；任务完成后会包含碳排放凭证。
cancel_task(task_id, series?)	取消已排队或已安排的任务；对于重复任务，可跳过该次任务，或使用 series: true 结束整个系列。
reply_task(task_id, text, deadline?)	继续已完成的任务：创建一项新任务，包含原对话和这段文本，并使用相同的提供商和模型。
expedite_task(task_id)	立即调度已排队或已安排的任务，不受其碳强度时段限制。
postpone_task(task_id, preset? | until? | delay_minutes?, reset_at?)	“稍后”：将待处理任务延后，绝不提前。预设值包括 1h、tonight（22:00 至 06:00）、tomorrow_morning（09:00 至 12:00）、after_limit_reset（Claude 限额重置后 5 分钟：使用 reset_at，否则使用此机器的限额读数，再否则使用之前给定的重置时间）。
update_deadline(task_id, deadline)	根据新的截止时间重新安排任务。
retry_task(task_id)	重新调度失败的任务。
cancel_all(status?)	取消所有仍处于排队或已安排状态的任务。
tidegap_usage(include_spend?)	只读：查看此机器的 Claude Code 订阅限额及其重置时间，以及来自本地日志的 Codex 限额。include_spend 会补充当前 5 小时窗口的令牌用量和按 API 目录价估算的费用。

环境变量

这些变量用于配置此 MCP 服务（以及读取同一组变量的 tidegap CLI）。它们会在服务自身的入口点读取，并注入 @tidegap/core；该模块不依赖环境变量，也不会自行读取任何环境变量。

OpenClaw 插件用户： @vitalini/tidegap OpenClaw 插件不会读取任何环境变量。请在网关配置的 plugins.entries.tidegap.config 下通过插件配置进行设置——下方“插件配置”列列出了替代各变量的字段。OpenClaw 会解析这些字段中的 "${ENV_VAR}" 简写，因此你可以继续导出相同的变量，让网关代替插件读取它们。

变量	插件配置	用途
TIDEGAP_ELECTRICITY_MAPS_API_KEY	electricityMapsApiKey	来自 electricitymaps.com 的 API 密钥。通用备用方案。如果未设置（且未配置特定区域的数据源），服务会回退到确定性模拟数据，因此你仍可在本地运行完整技术栈。
TIDEGAP_EIA_API_KEY	eiaApiKey	免费的 US EIA 密钥。为美国 ISO 区域（CAISO / ERCOT / ISO-NE / NYISO / PJM / MISO）启用平均排放强度数据。
TIDEGAP_ENTSOE_SECURITY_TOKEN	entsoeSecurityToken	免费的 ENTSO-E 令牌。为欧盟区域（FR / DE / ES / IT / NL）启用排放强度数据。
WATTTIME_USERNAME + WATTTIME_PASSWORD	wattTimeUsername + wattTimePassword	免费的 WattTime v3 账户。为美国 ISO 区域启用边际排放（co2_moer）预测——在数据覆盖范围内优先于 EIA；发生任何错误时则回退到 EIA。预测和收据会通过 signalType: "marginal" 标明边际信号。
TIDEGAP_DEFAULT_REGION	defaultRegion	工具调用未指定区域时使用的区域。优先级高于已存储的区域设置；请参阅电网区域。
ANTHROPIC_API_KEY	anthropicApiKey	启用 anthropic 提供方（支持批处理）。
OPENAI_API_KEY	openaiApiKey	启用 openai 提供方（支持批处理）。
GEMINI_API_KEY / GOOGLE_API_KEY	geminiApiKey / googleApiKey	启用 gemini 提供方（Generative Language API，仅支持同步调用）。优先使用 GEMINI_API_KEY；GOOGLE_API_KEY 为备用项。
OLLAMA_HOST	ollamaHost	启用本地 ollama 提供方（仅支持同步调用）。默认值为 http://localhost:11434；无需密钥——设置此变量即可启用该提供方。

电网区域

服务按以下顺序解析每次工具调用的区域：

1. 工具调用的 region 参数，
2. 服务环境中的 TIDEGAP_DEFAULT_REGION（Agent 主机的 MCP 配置），
3. 存储在此机器上的区域设置：tidegap region set <zone>，或在 tidegap ui 和 Mac 应用的“设置”→“电网区域”中设置（~/.tidegap/config 中的键为 TIDEGAP_DEFAULT_REGION），
4. 根据机器的时区推测，
5. GB。

文件变更时，服务会重新读取该设置，因此新设置会在下一次工具调用时生效，无需重启。如果存储的值不是受支持的区域，则会忽略该值，并针对每次变更输出一条 stderr 警告。schedule_task 的回复包含 region_source: flag | env | setting | timezone | fallback。

region 参数必须是 31 个受支持区域之一（大小写不限）。其他值会被拒绝，并显示最接近的区域以及申请添加区域的链接，例如 Unknown zone UA. Closest: PL. Request a region: <link>。如果设置了 TIDEGAP_ELECTRICITY_MAPS_API_KEY，则任何区域都可通过验证，因为 Electricity Maps 提供列表之外的区域；如果设置了 TIDEGAP_ENTSOE_SECURITY_TOKEN，则 IT 也可通过验证。

开发

在克隆仓库 https://github.com/tidegap/tidegap 的根目录中：

pnpm install
pnpm --filter @tidegap/mcp build
node packages/mcp-server/dist/server.js