Fettle

fettle-mcp

网站： fettle.sh · MCP 文档： fettle.sh/docs/mcp · 仪表板： dashboard.fettle.sh · 支持： [email protected]

Fettle 的 MCP 服务——可通过 Claude Code、Codex、Claude Desktop、Cursor、Windsurf 或任何支持 Model Context Protocol 的工具来操作的正常运行时间监控服务。

让你的助手创建监控项、查明某项监控为何中断、确认事件，或在部署前暂停检查——它调用的就是你也会使用的同一个公开 API。

"Add an HTTP monitor for https://api.acme.dev, check it every 5 minutes from Europe."
"Which of my monitors had incidents this week?"
"Pause the checkout monitor — we're deploying for the next 20 minutes."

在 官方 MCP 注册表 中，此服务的标识为 sh.fettle/mcp——一个条目涵盖两个通道，供通过注册表而非手动编辑的配置文件安装的客户端使用。

要求

• Node.js 20 或更高版本
• Fettle 账户和 API 密钥（在 https://fettle.sh 的“Settings → API Keys”中）

一个 API 密钥属于一个组织，并具有读取或写入权限。读取权限的密钥可以列出和查看信息；下方的写入工具需要使用具有写入权限的密钥。

安装

无需安装任何内容——MCP 客户端会按需使用 npx 运行此软件包。在客户端配置中添加一个条目，然后重启客户端。

Claude Code

claude mcp add fettle --env FETTLE_API_KEY=fettle_your_key_here -- npx -y fettle-mcp

Codex

codex mcp add fettle --env FETTLE_API_KEY=fettle_your_key_here -- npx -y fettle-mcp

也可以手动编辑 ~/.codex/config.toml（对于一个受信任的项目，则编辑 .codex/config.toml）：

[mcp_servers.fettle]
command = "npx"
args = ["-y", "fettle-mcp"]

[mcp_servers.fettle.env]
FETTLE_API_KEY = "fettle_your_key_here"

Claude Desktop

macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上的 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "fettle": {
      "command": "npx",
      "args": ["-y", "fettle-mcp"],
      "env": { "FETTLE_API_KEY": "fettle_your_key_here" }
    }
  }
}

Cursor

~/.cursor/mcp.json（全局）或 .cursor/mcp.json（每个项目）：

{
  "mcpServers": {
    "fettle": {
      "command": "npx",
      "args": ["-y", "fettle-mcp"],
      "env": { "FETTLE_API_KEY": "fettle_your_key_here" }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "fettle": {
      "command": "npx",
      "args": ["-y", "fettle-mcp"],
      "env": { "FETTLE_API_KEY": "fettle_your_key_here" }
    }
  }
}

配置

变量	必填	默认值	用途
FETTLE_API_KEY	是	—	你的 API 密钥。没有该密钥，服务将拒绝启动。
FETTLE_API_URL	否	https://api.fettle.sh	将服务指向其他 API。通常无需设置此项。
FETTLE_TIMEOUT_MS	否	30000	单次工具调用等待多久后会被放弃。

工具

共有 49 个工具，按操作对象分组。具有读取权限的密钥可调用标记为 read 的工具；所有标记为 write 的工具都需要具有写入权限的密钥。

每个工具都带有 MCP 提示 readOnlyHint、destructiveHint、idempotentHint 和 openWorldHint，因此客户端无需解析名称即可区分读取操作和更改操作，并仅在必要时请求确认。只有 5 个 delete_* 工具具有破坏性。preview_maintenance_window 和 check_target 虽然需要具有写入权限的密钥，但标记为只读：它们不会更改任何内容。check_now 和 check_target 会访问目标主机，因此属于开放世界操作。

所有结果为 JSON 对象的工具都会声明 outputSchema，并同时以 structuredContent 和文本形式返回结果，因此客户端可以读取带类型的字段，而不必解析文本。以下 4 个工具例外，仅返回文本：list_monitors（其紧凑行数据），以及结果为列表的 3 个工具——list_active_maintenance、preview_maintenance_window 和 list_channels。

监控项

工具	范围	功能说明
list_monitors	读取	简洁列出监控项（状态、目标、标签、SSL 到期时间），可按类型、状态和标签筛选。
get_monitor	读取	按 ID 查看一个监控项的完整配置和当前状态。
check_target	写入	在创建监控项前，从一个区域探测一次目标。
create_monitor	写入	创建一个按计划检查 URL、主机或端口的监控项。
bulk_create_monitors	写入	一次调用创建最多 100 个监控项——全部创建成功，否则全部不创建。
update_monitor	写入	更改现有监控项的设置。
bulk_update_monitors	写入	为最多 100 个监控项设置相同的间隔、区域、渠道或阈值；要么全部成功，要么全部不执行。
pause_monitor	写入	停止检查监控项，但不将其删除——计划停机前使用。
bulk_pause_monitors	写入	一次调用暂停最多 100 个监控项；要么全部成功，要么全部不执行。
resume_monitor	写入	恢复对已暂停监控项的检查。
bulk_resume_monitors	写入	一次调用恢复最多 100 个已暂停的监控项；要么全部成功，要么全部不执行。
delete_monitor	写入	软删除监控项：停止检查，并将其从监控项列表中移除。
check_now	写入	重新安排监控项在下一个调度周期运行，无需等待当前间隔结束。
get_exposed_ports_preset	读取	不应从互联网访问的数据库和管理端口。

结果和正常运行时间

工具	范围	功能说明
get_uptime_summary	读取	一次获取 24 小时 / 7 天 / 30 天内的正常运行时间、平均响应时间和事件数量。
get_uptime_daily	读取	按 UTC 日期查看监控项每天的正常运行时间，按时间从早到晚排列。
get_response_time_by_region	读取	查看监控项在 24 小时、7 天或 30 天内的平均响应时间，每个区域对应一条数据序列。
list_check_results	读取	列出监控项的单次检查结果，最新的排在前面，可按区域、状态或时间段筛选。

事件

工具	范围	功能说明
list_incidents	读取	列出事件，可按监控项、状态、原因或时间段筛选。
get_incident	读取	查看单个事件及其原因和所有告警尝试。
acknowledge_incident	写入	确认一个未解决的事件，以停止重复通知。

心跳

Tool	Scope	What it does
list_heartbeats	read	列出心跳（cron / 死人开关）监控项及每项最近一次收到 ping 的时间。
get_heartbeat	read	读取一个心跳，包括其 ping URL 及何时会被报告为延迟。
create_heartbeat	write	创建心跳监控项，并获取计划任务应 ping 的 URL。
update_heartbeat	write	更改心跳的名称、周期、宽限时间、频道或标签。
pause_heartbeat	write	暂停心跳：不会将其报告为延迟，且会忽略其 ping。
resume_heartbeat	write	恢复已暂停的心跳。
delete_heartbeat	write	永久删除心跳；其 ping URL 将停止工作。

维护窗口

Tool	Scope	What it does
list_maintenance_windows	read	列出维护窗口（一次性或定期、组织范围或针对单个监控项）。
list_active_maintenance	read	当前生效的维护窗口。
get_maintenance_window	read	读取一个维护窗口及其接下来的三次发生时间。
preview_maintenance_window	write	显示某个计划接下来会产生的三次发生时间，不保存计划。
create_maintenance_window	write	创建一个静默告警的窗口，可设置为一次性或按 iCal RRULE 计划定期执行。
update_maintenance_window	write	更改维护窗口。
delete_maintenance_window	write	删除维护窗口；告警将立即恢复。

标签

Tool	Scope	What it does
list_tags	read	列出组织中的所有标签，以及每个标签关联的监控项和心跳数量。
bulk_update_monitor_tags	write	一次调用即可为最多 300 个监控项添加和／或移除标签。
rename_tag	write	重命名所有关联了该标签的监控项和心跳上的标签。
delete_tag	write	从所有关联了该标签的监控项和心跳中移除该标签。

状态页

工具	范围	功能说明
list_status_pages	read	列出状态页，并显示每个页面的 slug 及其是否已发布。
get_status_page	read	读取一个状态页及其分组和组件。
list_status_page_incidents	read	列出状态页的事件，包括由人员发布或由 Fettle 创建的事件及其时间线。
create_status_page_incident	write	在状态页上创建事件并发布第一条消息。
post_status_page_update	write	向状态页事件添加消息并设置其状态；RESOLVED 会关闭该事件。
update_status_page_incident	write	重命名状态页事件；不会通知订阅者。
delete_status_page_incident	write	从状态页中移除事件及其时间线。

组织与平台

工具	范围	功能说明
get_plan_usage	read	组织的套餐、套餐限制，以及各项限额的使用量。
list_channels	read	列出可绑定到监控器的通知渠道（id、type、label、verified）。
list_regions	read	列出检查区域及 regions 参数所接受的区域代码。

工具列表并非手动编写。它由 Fettle 后端根据一个注册表生成，并通过 /public-api/mcp-tools.json提供； 此软件包内置该文件，并在启动时据此构建工具，因此两个 MCP 通道提供的工具不会有差异。

Agent 指南

服务端会在 initialize 时通过 instructions 将本指南发送给客户端，因此通过任一通道连接的 Agent 都已收到指南。此处重现指南，供人阅读，也供不会显示服务端指令的客户端使用。

Fettle is an uptime monitoring service. The tools see only the API key's organization: monitors, heartbeats, maintenance windows, incidents, status page incidents, tags, channels (read), regions. Channels, status pages, members, API keys and billing are managed only in the dashboard (https://dashboard.fettle.sh). Read a tool's description (arguments, limits, errors) before its first call.

FINDING THINGS
- list_monitors: one short row per monitor, to find ids. Filters are JSON arrays. Broken now: status ["DOWN", "DEGRADED"]. Certificates expiring first: type ["SSL"], sort "ssl_expiry".
- tag filters lists; tag_match "all" (default) needs every tag, "any" one of them.
- Pages: page from 1, size 1..100 (default 25).

PLAN LIMITS
Call get_plan_usage before creating anything: limits (null means none) and usage. A broken limit or an unknown region is a 403 naming it: change the request or tell the user; never retry it unchanged.

CREATING MONITORS
- check_target probes a target once before create_monitor.
- regions: unless the user names some, use every limits.allowed_regions code, up to max_regions; SSL, DNS and port-list TCP take one.
- After create, tell the user the interval and regions chosen; offer to change the interval (update_monitor).
- bulk_create_monitors creates up to 100, all or nothing.
- type and target never change after create.
- channel_ids: ids from list_channels. Empty or omitted on create alerts every verified, active channel. Email is not a channel: every alert also emails the creator of the monitor or heartbeat.
- update tools change only the fields you pass; omit one to keep it, never send null. A monitor's config is replaced whole: resend every config field to keep.
- Exposed ports on a server: follow get_exposed_ports_preset.

MANY MONITORS AT ONCE
Find ids with list_monitors, then bulk_pause_monitors, bulk_resume_monitors or bulk_update_monitors (interval, timeout, regions, channels, threshold, cooldown) for up to 100 ids, all or nothing. bulk_update_monitor_tags adds or removes tags on up to 300. There is no bulk delete.

TAGS
Call list_tags first and reuse names. Tags are flat labels such as env:prod, trimmed, lowercased and deduplicated; at most 10 per item. rename_tag and delete_tag act on every monitor and heartbeat.

HEARTBEATS
A job calls ping_url when it succeeds. Job every N seconds, alert after T seconds of silence: period_seconds = N, grace_seconds = T - N. Never late before its first success ping. ping_url + "/start" restarts the clock, ping_url + "/fail" marks it DOWN at once.

MAINTENANCE
Before a deploy or reboot, create_maintenance_window (scope ORG or MONITOR) instead of pausing monitors: checks keep running, but no incident opens and no alert goes out. Not for heartbeats. preview_maintenance_window shows a schedule's next occurrences; list_active_maintenance shows what is silenced now.

OUTAGES
list_monitors status ["DOWN"] -> list_check_results (status code, error, region per check) -> get_incident. acknowledge_incident stops repeat alerts; the recovery alert still goes out. create_status_page_incident and post_status_page_update can email the page's subscribers: confirm the text with the user first.

ERRORS (start of a failed call's text)
- "Authentication failed": the key is missing, revoked or expired, the address is not allowed, or its creator lost access. Do not retry; tell the user.
- "This tool requires/needs an API key with write scope": the key is read-only; tell the user.
- "Invalid argument(s)": names each failing field. "Invalid request:": the rule broken. Fix, retry.
- "Forbidden:": a plan limit, an unknown region, or the key's user lacks the permission; the reason says which.
- "Not found:": no such id in this organization.
- "Rate limited": wait the seconds given, then retry. All API keys share the organization's per-minute budget.
- "Tool '<name>' failed: the API returned 5xx": server fault, retry once later.
- "Tool '<name>' does not accept argument(s)": drop the ones named.
- "Request failed with status N": read the reason, do not retry unchanged.

另一个通道：远程 MCP

如果客户端支持通过 HTTP 使用远程 MCP 服务，则完全不需要此软件包——只需使用与 Bearer token 相同的 API 密钥连接到 https://api.fettle.sh/mcp。工具相同，行为相同，无需安装或更新。

Claude Code 可通过命令行添加远程通道——使用的标志集与上面的 stdio 通道不同，密钥作为标头传入，而不是环境变量：

claude mcp add fettle --transport http https://api.fettle.sh/mcp \
  --header "Authorization: Bearer fettle_your_key_here"

通过 JSON 文件配置的客户端使用相同的两个字段：

{
  "mcpServers": {
    "fettle": {
      "url": "https://api.fettle.sh/mcp",
      "headers": { "Authorization": "Bearer fettle_your_key_here" }
    }
  }
}

Codex 在 ~/.codex/config.toml 中配置远程通道，并从环境变量读取密钥，因此密钥不会保存在文件中：

[mcp_servers.fettle]
url = "https://api.fettle.sh/mcp"
bearer_token_env_var = "FETTLE_API_KEY"

当客户端只支持 stdio，或者你希望凭据保存在本地配置文件中，而不是客户端的云配置中时，请使用此软件包。

目前两个通道都不支持 OAuth；两者均使用 API 密钥进行身份验证。

速率限制与套餐

工具调用消耗的组织级请求额度与 REST API 相同，使用套餐限额，而非单独的额度。触发速率限制时，调用会返回需要等待的秒数。check_now 另有独立上限：每个调用地址每分钟最多调用 10 次。get_plan_usage 会通过 limits.api_rate_limit_per_minute 显示组织的请求额度。套餐限额请见 https://fettle.sh/pricing。

故障排除

FETTLE_API_KEY is not set — 客户端启动服务时未设置该变量。检查上方配置中的 env 块，然后彻底重启客户端：大多数客户端只会在启动时读取 MCP 配置。

Authentication failed — 密钥错误、已撤销，或来自已删除的组织。请在 Settings → API Keys 中创建一个新密钥。

This tool requires an API key with write scope — 该密钥为只读密钥。请创建一个具有写入权限的密钥；无法扩大现有密钥的权限范围。

助手看不到这些工具 — 重启客户端，然后通过 node -v 确认 Node.js 版本为 20+。在终端中运行 npx -y fettle-mcp：它应打印缺少密钥的消息并退出，这可以证明软件包本身正常运行。

开发

pnpm install
pnpm run typecheck
pnpm test
pnpm run build
pnpm run contract:check        # vendored contract vs. production

添加工具需要修改后端的注册表，而不是这里：在后端重新生成契约，然后使用 pnpm run contract:check -- --write 重新引入契约，并提交结果。本软件包中没有描述工具的源文件。

server.json 是官方 MCP 注册表 提供的入口文件，其中也重复记录了版本号——如果版本号与 package.json 不再匹配，测试就会失败，因此请同时更新两者。

发布通过版本标签完成：推送 vX.Y.Z 会运行 .github/workflows/publish.yml， 该流程会测试、构建软件包，并将其连同来源证明发布到 npm。

许可证

MIT © Fettle