PetKit

mcp-server-petkit

适用于 PetKit 云 API 的 MCP（Model Context Protocol）服务。将 Fresh Element Solo（设备类型 D4）的喂食器状态和控制功能作为 MCP 工具开放。

免责声明： 本项目与 PetKit 无关，也未获其认可或以任何方式与其关联。这是由一位硬件和软件用户开发的独立社区集成项目。PetKit 和 Fresh Element Solo 是其各自所有者的商标。使用本软件包的风险由您自行承担。底层 API 并非官方 API，由社区通过逆向工程实现；它可能随时变更或失效，恕不另行通知。

工具

工具	描述
list_feeders	列出所有 Fresh Element Solo 喂食器及其实时状态（食物、电池、干燥剂状态，锁定、灯光、声音设置，以及今日喂食总量）
feed_now	立即投放食物
update_feeder_setting	更改数值设置（儿童锁、指示灯、投放提示音、缺粮警报等）
skip_scheduled_feed	跳过今天的一次计划喂食（d4/removeDailyFeed），不影响重复计划
restore_scheduled_feed	撤销今天的一次跳过操作（d4/restoreDailyFeed）

喂食量

D4 仅接受以下五种份量：10、20、30、40、50。

喂食总量按设备统计，而非按猫统计

list_feeders 还会返回 feedPlanToday：喂食器每周计划中的今日计划喂食（来自 d4/device_detail 的 multiFeedItem），每项包含易读的 time、skip_scheduled_feed 所需的 feedTime（自午夜起的秒数）、以 feed_now 所用单位表示的份量 amount，以及餐次名称 name。

list_feeders 还会返回 dispenseLogToday（来自 d4/dailyFeeds）：今天已完成的所有投放记录，按时间从早到晚排列。dispensedAt 是投放在您所在时区实际发生的时间（dispensedAtUtc 为 UTC），而 feederClock 是喂食器自身时钟显示的时间；如果该时钟不准确，二者就会不同。clockOffsetMinutes 根据最近一次投放汇总时钟偏差，并四舍五入到 15 分钟。例如，喂食器未切换到冬令时、每餐都提前一小时投放时，该值为 60；当天首次投放之前则为 null。PetKit 没有可直接读取喂食器时钟的接口。给喂食器断电再通电后，它会同步到新时间。

list_feeders 的 fedToday/fedTodayScheduled/fedTodayExtra/fedTodayPlanned/dispensesToday/feedTimesToday 字段反映每台实体喂食器投放的食物量——PetKit 无法将投放记录归属到特定的猫。如果您的猫共用彼此的食盆，或会偷吃彼此的食物，这些数字就无法说明某只猫实际吃了多少。

常见设置键

键	含义
manualLock	儿童锁（0/1）
lightMode	指示灯
feedSound	投放提示音（0/1）
foodWarn	缺粮警报（0/1）

设备通过 list_feeders 报告的其他数值键也可能有效，但尚未确认。

配置

启动服务前，请设置以下环境变量：

export PETKIT_EMAIL="[email protected]"
export PETKIT_PASSWORD="yourpassword"
export PETKIT_REGION="Netherlands"   # must match the exact region name shown in the PetKit app
export PETKIT_TIMEZONE="Europe/Amsterdam"   # optional, defaults to the host's own timezone

注意： PetKit 账户密码长度限制为 6-14 个字符。密码过长会导致登录失败，并显示通用的“用户名或密码错误”提示，无法与密码确实错误的情况区分。如果登录意外失败，请先检查密码长度。

在 Claude Desktop 中使用

将以下内容添加到您的 claude_desktop_config.json：

{
  "mcpServers": {
    "petkit": {
      "command": "npx",
      "args": ["mcp-server-petkit"],
      "env": {
        "PETKIT_EMAIL": "[email protected]",
        "PETKIT_PASSWORD": "yourpassword",
        "PETKIT_REGION": "Netherlands"
      }
    }
  }
}

远程使用：claude.ai 连接器（HTTP + OAuth）

如需从 claude.ai 和 Claude 移动应用使用该服务，请在一台始终开机的设备上以 HTTP 模式运行，并将其添加为自定义连接器。claude.ai 从互联网连接，因此服务需要一个公开的 https:// URL。Cloudflare Tunnel 或 Tailscale Funnel 可以提供这样的 URL，无需在路由器上开放端口（见下文）。

HTTP 模式为单用户模式：连接 Claude 时，服务会显示一个页面，要求输入你的所有者密码短语。知道密码短语的人都可以授权客户端，而持有令牌的人都可以投放食物或更改喂食计划——请选择一个足够强的密码短语。

npx mcp-server-petkit --http   # or MCP_TRANSPORT=http

变量	默认值
MCP_PUBLIC_URL	（必填）	claude.ai 访问该服务所用的 https:// URL
MCP_OWNER_PASSWORD	（必填）	用于授权 Claude 的密码短语，至少 12 个字符
MCP_HOST	127.0.0.1	监听的接口；Docker 镜像会设置为 0.0.0.0
MCP_PORT	3000
MCP_STATE_FILE	~/.mcp-server-petkit/oauth-state.json	已注册的客户端和刷新令牌哈希，以便 Claude 在重启后保持连接

以及 配置 中的 PETKIT_* 变量。

Docker（例如，在 Raspberry Pi 上）

每个版本都会发布适用于 amd64、arm64 和 arm/v7（32 位 Raspberry Pi OS）的 ghcr.io/dirkjanfaber/mcp-server-petkit，并以版本号和 latest 标记。将 PetKit 和 MCP_* 设置放入 compose 文件旁的 .env 文件中（chmod 600 .env），并通过以下两种方式之一为服务提供公开 URL。

ZeroTier 或普通 Tailscale 等私有覆盖网络本身并不足够：claude.ai 从 Anthropic 的服务器连接，而不是从你的设备连接。

选项 1：Cloudflare Tunnel（需要在 Cloudflare 上拥有域名）

将 Cloudflare Tunnel 与服务一起运行，无需发布任何端口：在 Cloudflare 控制面板中，前往 Zero Trust → Networks → Tunnels，创建一个 Cloudflared 隧道，并将其公共主机名指向 http://petkit-mcp:3000（服务类型为 HTTP）。将隧道令牌放入 .env，变量名为 TUNNEL_TOKEN：

# docker-compose.yml
services:
  petkit-mcp:
    image: ghcr.io/dirkjanfaber/mcp-server-petkit:latest   # or pin a version, e.g. :0.3.0
    restart: unless-stopped
    env_file: .env   # PETKIT_*, MCP_PUBLIC_URL, MCP_OWNER_PASSWORD
    volumes:
      - petkit-data:/data
  cloudflared:
    image: cloudflare/cloudflared:latest
    command: tunnel run
    restart: unless-stopped
    environment:
      TUNNEL_TOKEN: ${TUNNEL_TOKEN}
volumes:
  petkit-data:

不要在主机名前启用 Cloudflare Access：claude.ai 无法通过其登录页面，而所有者密码短语已经为服务提供保护。

选项 2：Tailscale Funnel（无需域名）

Tailscale Funnel 会为 Pi 提供一个公开的 https://<machine>.<tailnet>.ts.net URL。它可以与 ZeroTier 或其他 VPN 一起正常运行。

1. 在 Pi 上安装 Tailscale 并登录： curl -fsSL https://tailscale.com/install.sh | sh && sudo tailscale up

2. 在 Tailscale 管理控制台中，启用 MagicDNS 和 HTTPS Certificates（位于 DNS 下），并允许该设备使用 Funnel。如果尚未允许，tailscale funnel 会提供启用链接。

3. 仅在环回接口上发布服务端口，这样 Funnel 就是唯一的访问途径：

   # docker-compose.yml
   services:
     petkit-mcp:
       image: ghcr.io/dirkjanfaber/mcp-server-petkit:latest
       restart: unless-stopped
       env_file: .env   # PETKIT_*, MCP_PUBLIC_URL, MCP_OWNER_PASSWORD
       ports:
         - "127.0.0.1:3000:3000"
       volumes:
         - petkit-data:/data
   volumes:
     petkit-data:
   

4. 启动 Funnel。此设置会在重启后保留： sudo tailscale funnel --bg 3000。tailscale funnel status 会显示公开 URL。将其放入 .env，变量名为 MCP_PUBLIC_URL，然后运行 docker compose up -d。

URL 中包含设备名称，因此如果想使用更好看的名称，请先重命名设备。之后更改 URL 时，需要更新 MCP_PUBLIC_URL 并重新连接 Claude。

两种方式均适用

连接 Claude 前，请检查公开 URL：

curl https://<your public host>/.well-known/oauth-authorization-server

它应返回 JSON，且其中的 issuer 与 MCP_PUBLIC_URL 一致。刚启用的 Funnel 可能需要一分钟才能开始响应。

使用 docker compose pull && docker compose up -d 更新。如果要自行构建镜像，请将 image: 替换为 build: https://github.com/dirkjanfaber/mcp-server-petkit.git。

该服务会信任一个代理跳数（来自前置隧道的 X-Forwarded-For），用于速率限制。不要同时将服务端口直接发布到互联网。

连接 Claude

在 claude.ai 中：Settings → Connectors → Add custom connector，URL 为 https://<your public host>/mcp。Claude 会自行注册，打开密码短语页面； 你允许连接后，工具便会显示在 claude.ai 和移动应用中。

**PetKit 每个账户仅允许一个会话。**服务端登录会让 PetKit 应用退出登录 （反之亦然）；发生这种情况时，服务端会自动重新登录，但每当服务端重启或 会话失效时，都可能需要你重新登录应用。在同一账户下运行 stdio 服务、 Node-RED 的 PetKit 节点或第二个 HTTP 实例，会导致它们轮流让彼此退出登录。

参考资料

• 积极维护的参考客户端（Python）- https://github.com/Jezza34000/py-petkit-api - 已确认可用的客户端指纹和当前端点常量的来源
• 包含更完整协议说明的同系列 Node-RED 软件包 - node-red-contrib-petkit 的 CLAUDE.md