VoiceOS Instagram インテグレーション

Mac のノッチから音声で Instagram アカウントを操作できます。アカウントの調子を尋ねたり、コメントや DM を読んだり、写真やカルーセルをノッチにドロップしてキャプションを口述して投稿したりできます。

ビジネスアカウントまたはクリエイターアカウントが必要です。 Instagram の API は、個人アカウントではインサイト、コメント、DM、投稿を公開しません。これは Meta のルールであり、当社のルールではありません。回避策はありません。

変換方法: Instagram アプリ → 自分のプロフィール → ☰ メニュー → 設定とプライバシー → アカウントの種類とツール → プロフェッショナルアカウントに切り替え。「クリエイター」または「ビジネス」を選択し、プロンプトに従ってください。無料で、元に戻せます。また、アカウントが非公開だった場合も公開にはなりません。その後、このインテグレーションを再接続してください。

セットアップ

6 つのステップです。ステップ 3 と 4 は投稿したい場合にのみ必要です。閲覧だけなら不要です。

1. 依存関係をインストール

cd instagram
bun install

2. Composio を通じて Instagram を接続

Composio は、このインテグレーションが動作する認証および API 転送基盤です。

1. Composio ダッシュボードから API キーを取得します。

2. Composio プロジェクトに Instagram をアプリとして追加します。これにより、接続フローに必要な認証設定が作成されます。

実際の Instagram OAuth の承認はステップ 6 で行います。ここではまだ何もする必要はありません。

3. 写真リレーバケットを作成（Cloudflare R2）

Instagram は画像バイトデータを直接受け付けません。Meta は独自のクローラーで公開 URL を取得します。そのため、ノッチにドロップした写真は自分の R2 バケットにアップロードされ、リンクとして Instagram に渡され、数秒後に削除されます。

Cloudflare ダッシュボード → R2 で:

1. バケットを作成します。

2. バケットを開く → 設定 → パブリック開発 URL → 有効化。その URL をコピーします。Meta が写真を取得できないため、バケットは公開である必要があります。

3. API トークンを管理 → API トークンを作成し、その 1 つのバケットに限定し、オブジェクトの読み取りと書き込み権限を付与します。シークレットは一度だけ表示されます。今すぐコピーしてください。

4. 任意ですが推奨: 1 日後にオブジェクトを削除するライフサイクルルールを追加します。インテグレーションは各写真を自分で削除します。これはまれな失敗時の保険です。

閲覧のみの場合はこのステップ全体をスキップしてください。 account_pulse、post_insights、activity、dm_thread はすべてバケットなしで動作します。バケットが必要なのは create_post と schedule_post だけです。

4. サーバーにキーを渡す

このフォルダに .env ファイルを作成します:

COMPOSIO_API_KEY=

# Cloudflare R2 — publishing only, leave blank if you are read-only
R2_ACCOUNT_ID=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_BUCKET=
R2_PUBLIC_URL=

R2_ACCOUNT_ID は Cloudflare の R2 → 概要 ページの右上にあります。R2_PUBLIC_URL はステップ 3 のパブリック開発 URL です。

VoiceOS がセットアップフィールドとしてこれらの入力を求めてきた場合、その入力が優先され、ファイルはサーバーを単独で実行する場合のフォールバックにすぎません。

5. VoiceOS にインストール

先に VoiceOS を終了してください。 VoiceOS は config.json をメモリに保持し、終了時に書き換えるため、実行中に書き込まれた内容はエラーもなく静かに破棄されます。インストーラーは VoiceOS が起動しているのを検出すると実行を拒否します。

osascript -e 'quit app "VoiceOS"'
python3 install-into-voiceos.py
open -a VoiceOS

これにより、このフォルダが ~/Library/Application Support/VoiceOS/custom-mcps/ にコピーされ、ステップ 4 のキーが引き継がれ、登録されます。単純な cp では不十分です。VoiceOS は config.json に 2 つのエントリ（サーバーの起動方法を示すものとマニフェストを運ぶもの）も必要とし、それらを書き込むことがスクリプトの作業の大部分です。スクリプトは最初に config.json をバックアップします。

--update は毎回マニフェストから confirmTools を再導出します。これは見た目以上に重要です。これは VoiceOS が確認カードを必要とするツールを判断するリストであり、リネーム後に残った古いエントリがあると、カードなしで投稿が公開されてしまう可能性があります。

6. アカウントを接続

「私の Instagram はどう？」 と話しかけてください。Instagram がまだリンクされていない場合は、OAuth リンク付きの Instagram に接続 カードが表示されます。一度承認すれば完了です。

アカウントが個人と表示された場合は、このページ上部のボックスに戻ってください。

ツール

写真をノッチにドロップし、同じ息で話しかけてください — 「この 2 枚をハッカソンのキャプション付きで投稿して」。両方の書き込みツールは、何かを公開する前に、写真、キャプション、（予約の場合は）正確な時刻をカードで表示します。

写真の処理方法

一度読む価値があります。驚くステップが 1 つあるからです。

1. 写真は Mac 上で sips（macOS に組み込み）を使用して JPEG に変換されます。Instagram は他の形式を受け付けません。

2. ランダムで推測不可能な名前で自分の R2 バケットにアップロードされ、数秒間公開読み取り可能になります。これは避けられません。Meta のクローラーは匿名でログインできないため、公開 URL が Instagram が写真を受け取る唯一の方法です。

3. Instagram が写真を取得して投稿を公開します。

4. ファイルはバケットから削除されます — 成功時も失敗時も、finally ブロックで削除されます。ステップ 3 のライフサイクルルールが保険です。

バケットはあなたのものです。他の誰かのサーバーに保存されるものはなく、このインテグレーションは写真のコピーを保持しません。

予約投稿は Instagram のサーバーではなく Mac 上で実行されます — Instagram には予約投稿 API がありません。macOS の launchd タイマーが指定した分に起動して公開します。そのため、Mac が起動していてスリープしていない必要があります。投稿予定時刻に Mac がシャットダウンしていた場合、投稿は数時間遅れて公開されるのではなく未達として記録され、次回 instagram_activity で確認できます。

v1 に含まれないもの

意図的に削除されたものです。試す前に知っておいてください:

• DM の送信。 Meta は Composio の共有 Instagram アプリを通じた API による DM 送信をブロックしています。24 時間ウィンドウが確実に開いている場合でも「許可されたウィンドウ外」エラーを返します。インテグレーションは DM を読み取ることはできますが、送信はできません。Instagram アプリで返信してください。

• コメントへの返信。 同じ転送の制限です。

• 動画とリール。 写真と写真カルーセルのみです。動画公開には、このビルドにはない再開可能なアップロードパスが必要です。

• ストーリー。 ツールキットでは公開されていません。

• 24 時間を超える予約。 上限は意図的です。1 時間ごとに、遅延ジョブが誰にも見えない場所で腐敗する方法が増えます — 写真が削除されたり、キーがローテーションされたり、接続が取り消されたりします。

• 他のアカウントの閲覧。 接続したアカウントのみです。

トラブルシューティング

開発

bun install
bun test          # 224 unit and failure-injection tests
bunx tsc --noEmit -p tsconfig.json

テストが保護するために存在する 3 つのルール。編集前に知っておく価値があります:

• stdout は MCP の配線です。 出荷コードに console.log が 1 つあるだけで VoiceOS は JSON-RPC ストリームを解析できなくなり、アプリを再起動するまでインテグレーションはルーティングから静かに消えます。すべてのログは console.error を通じて出力されます。stdoutGuard.ts は server.ts の最初のインポートであり、そうしない依存関係のためにコンソールを再バインドします。

• ファイルパスからシェル文字列を構築しないでください。 写真はユーザーがファイルをノッチにドラッグすることで提供されます。execFile(cmd, [args]) のみを使用してください。holiday.png; rm -rf ~ という名前のファイルは sips にとって 1 つの不透明な引数であり、test/media-paths.test.ts がそれを検証します。

• ツール名と説明はマニフェストと正確に一致する必要があります、双方向で。server.ts と voiceos.integration.json は 1 つの契約の 2 つのコピーです。

confirmations/post_composer.html は公開前カードのソースオブブトゥルースです。マニフェストはそのコピーを文字列として保持します。HTML を編集した場合はコピーを再生成する必要があります。そうしないと、取り消し不可能な公開の前に表示されるカードが古いものになります。