Instagram Story MCP

YouTube・TikTok・Instagram投稿をInstagramストーリーズへ共有するための、ローカルstdio MCPです。アカウント確認、プレビュー、親しい友達への公開、既存ハイライトへの追加、処理結果の照会を提供します。

URLの取得・動画変換・MCPをこのパッケージにまとめています。Instagramへの通信、認証、公開の検証と投稿台帳には、別に配置した Instagram HTTP Relay を使います。普段の操作でブラウザーは起動しません。

必要な環境

• Python 3.11以降

• Node.js 24、pnpm 11.5.0

• ffmpeg と ffprobe がPATHから実行できること

• HTTPモードで設定・ビルド済みのRelay

Python用のMCP SDK、yt-dlp、curl-cffi、Pillowはインストール時に導入します。MCP SDKは検証済みの1.26.0へ固定しています。

Related MCP server: insta-mcp

導入

git clone https://github.com/shirafukayayoi/instagram-story-mcp.git
cd instagram-story-mcp
python -m venv .venv
.venv\Scripts\python.exe -m pip install .

Linuxでは .venv/Scripts/python.exe を .venv/bin/python に読み替えてください。開発時は pip install -e . を使えます。

Relayは feat/account-switching ブランチの e2c4b9c 以降を利用してください。この版には文面なし動画のモバイル形式での公開と、投稿時の本人コメントの照合が含まれます。

git clone --branch feat/account-switching https://github.com/shirafukayayoi/instagram_api_safe_relay.git
cd instagram_api_safe_relay
pnpm install --frozen-lockfile
pnpm build

Relayの settings.json、.env、専用のセッションをローカルで設定します。HTTPモードの導入手順を参照してください。

• 全プロファイルの browser.type を http にする。

• stories.enabled を有効にし、Relayの work/story-smoke を素材許可ディレクトリへ含める。

• Instagram投稿のカード共有を使う場合は stories.feedPostSharingEnabled も有効にする。

• HTTPモードではDMとメンション受付を無効にする。

• Relayの .env へ INSTAGRAM_RELAY_API_TOKEN を保存する。

初回ログイン・追加認証は手動で行います。既存のセッションや台帳を削除しません。認証ファイルはこのMCPリポジトリへコピーせず、Relay側のGit管理外に保持します。

Codexへの登録

MCPリポジトリのルートから、配置先を実環境の絶対パスに置き換えて実行します。

$mcpPython = (Resolve-Path '.venv\Scripts\python.exe').Path
codex mcp add instagram --env 'INSTAGRAM_RELAY_REPOSITORY=C:\path\instagram_api_safe_relay' --env PYTHONUTF8=1 -- $mcpPython -m instagram_story_mcp

~/.codex/config.toml の登録にタイムアウトを指定します。BearerやCookieはここへ書きません。

[mcp_servers.instagram]
command = 'C:\path\instagram-story-mcp\.venv\Scripts\python.exe'
args = ["-m", "instagram_story_mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 600
env = { INSTAGRAM_RELAY_REPOSITORY = 'C:\path\instagram_api_safe_relay', PYTHONUTF8 = "1" }

MCPクライアントを再接続し、instagram_status で ready: true、選択中のアカウントを確認します。停止中のRelayは必要時に起動し、稼働中ならそのまま利用します。配置先の環境変数が未設定でもツール一覧は取得でき、実際の操作は設定を求めて停止します。

ツール

投稿の流れ

1. 接続と選択中のアカウントを確認する。

2. instagram_preview_url へURLと公開範囲を渡す。親しい友達は close_friends、通常公開は all。コメント、動画の切り出し、ハイライトは初回から指定する。

3. プレビューの投稿先、公開範囲、素材を確認する。プレビューではInstagramへアップロード・公開しない。

4. ユーザーの明示的な投稿依頼がある場合に、返された operationId、preview.account.id、preview.audience を instagram_publish_operation へ渡す。

5. 投稿は result.state: published とメディアID、アカウント、公開範囲を確認する。ハイライトは別に highlightResult.state: completed を確認する。

楽曲紹介のコメントは、確認できた「曲名 / アーティスト名」を基本にします。投稿者名からアーティストを推定しません。会話動画などへのコメントは任意です。文面は投稿時の本人コメントとして送り、画像・動画へ文字を焼き込みません。

動画はH.264/AACまたは音声なしのMP4、1〜60秒、100MiB以下が対象です。横動画は縦のキャンバスへ変換し、原本を保存します。勝手な音声差し替えや自動分割は行いません。60秒を超える動画は、ユーザーが指定した範囲を切り出します。

再開と結果不明

操作IDを省略した初回プレビューではUUIDを作ります。再開時は同じIDと引数を指定します。プレビューの有効期限は10分で、期限切れは同じ操作IDで更新します。

公開要求は確認済みプレビューのIDで1回だけ送り、送信前に台帳へ記録します。受理済み・公開済み・結果不明の操作で公開ツールを再び呼んだ場合は状態照会だけを行います。接続が切れても、新しいIDで自動再投稿しません。

ハイライトの unknown も再追加しません。対象の動画がハイライトに存在しても、登録前後の既存一覧の維持を確認できなければ、厳密な完了状態は unknown のまま保持します。投稿とハイライトの成否を分けて報告してください。

子プロセスの標準入力・出力・エラーをMCPの通信パイプから分離しています。Windowsで子Pythonが起動時に停止する問題の回帰テストを含みます。子プロセスの生出力や、署名付き素材URLをMCPへ返しません。

テスト

インストール後、ネットワークや実アカウントを使わないテストを実行できます。

.venv\Scripts\python.exe tests/test_server.py
.venv\Scripts\python.exe -m pip wheel --no-deps . --wheel-dir dist

設定済みRelayの接続確認だけを行う場合：

$env:INSTAGRAM_RELAY_REPOSITORY = 'C:\path\instagram_api_safe_relay'
.venv\Scripts\python.exe tests/test_server.py --live

--live でも投稿やハイライト追加は行いません。CIはLinuxのPython 3.11/3.14とWindowsのPython 3.14で、境界テスト、stdio接続、wheelビルドを実行します。

ライセンスと元の実装

MIT License。元の実装と変更点は NOTICE.md を参照してください。