PetKit

mcp-server-petkit

PetKit クラウド API 用の MCP（Model Context Protocol）サーバーです。Fresh Element Solo（デバイスタイプ D4）の給餌器の状態確認と操作を MCP ツールとして提供します。

免責事項： このプロジェクトは PetKit と提携、承認、またはいかなる形でも関係しているものではありません。ハードウェアとソフトウェアを愛用するユーザーが開発した、独立したコミュニティ製の統合機能です。PetKit および Fresh Element Solo は、それぞれの所有者の商標です。このパッケージは自己責任でご利用ください。基盤となる API は非公式で、コミュニティによるリバースエンジニアリングで実現されています。予告なく変更されたり、動作しなくなったりする可能性があります。

ツール

ツール	説明
list_feeders	すべての Fresh Element Solo 給餌器とその現在の状態（フード／バッテリー／乾燥剤の状態、ロック／ライト／サウンドの設定、本日の給餌合計）を一覧表示します
feed_now	すぐに給餌します
update_feeder_setting	数値設定を変更します（チャイルドロック、インジケーターライト、給餌音、不足アラームなど）
skip_scheduled_feed	本日の予定された給餌を 1 回スキップします（d4/removeDailyFeed）。繰り返しのプランは変更されません
restore_scheduled_feed	本日分のスキップを取り消します（d4/restoreDailyFeed）

給餌量

D4 で設定できる給餌量は、10、20、30、40、50 の 5 種類のみです。

給餌合計は猫ごとではなく、デバイスごとの値です

list_feeders は feedPlanToday も返します。これは給餌器の週間プラン（d4/device_detail の multiFeedItem）に登録された本日の予定給餌で、それぞれ読みやすい形式の time、skip_scheduled_feed に渡す feedTime（午前 0 時からの秒数）、feed_now で使用する単位での給餌量 amount、給餌名 name を含みます。

list_feeders は dispenseLogToday（d4/dailyFeeds から取得）も返します。これは本日完了したすべての給餌を古い順に並べたものです。dispensedAt はお使いのタイムゾーンで実際に給餌が行われた時刻（UTC では dispensedAtUtc）で、feederClock は給餌器本体の時計が示した時刻です。そのため、給餌器の時計がずれていると両者の時刻も異なります。clockOffsetMinutes は最新の給餌時刻から計算したずれを 15 分単位に丸めた値です。たとえば、冬時間への切り替えに対応できず、毎回 1 時間早く給餌する給餌器では 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。公開 URL は tailscale funnel status で確認できます。これを .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

issuer が MCP_PUBLIC_URL と一致する JSON が返されるはずです。有効化したばかりの Funnel が応答を開始するまで、1 分ほどかかることがあります。

docker compose pull && docker compose up -d で更新します。代わりに自分でイメージをビルドするには、image: を build: https://github.com/dirkjanfaber/mcp-server-petkit.git に置き換えます。

サーバーは、レート制限のためにプロキシの 1 ホップ（前段のトンネルからの X-Forwarded-For）を信頼します。サーバーのポートをインターネットに直接公開しないでください。

Claude への接続

claude.ai で、Settings → Connectors → Add custom connector を選び、URL に https://<your public host>/mcp を指定します。Claude が登録を行い、パスフレーズのページが開きます。 許可すると、ツールが claude.ai とモバイルアプリに表示されます。

PetKit では、アカウントごとにセッションは1つだけ使用できます。 サーバーでログインすると PetKit アプリからログアウトされ、その逆も同様です。ログアウトが発生するとサーバーは自動的に再ログインしますが、サーバーの再起動時やセッションの期限切れ時には、アプリで再度ログインを求められることがあります。 同じアカウントで stdio サーバー、Node-RED の PetKit ノード、または2つ目の HTTP インスタンスを実行すると、それぞれが交互に相手をログアウトさせます。

参考資料

• 積極的にメンテナンスされている参考クライアント（Python） - https://github.com/Jezza34000/py-petkit-api - 動作確認済みのクライアントフィンガープリントと現在のエンドポイント定数の情報源
• プロトコルに関するより詳しい説明を含む関連 Node-RED パッケージ - node-red-contrib-petkit の CLAUDE.md