Claude CodeにPostizプラグインを入れてSNSの予約投稿を任せる

PostizプラグインはClaude Codeにスキルを1つ足すだけのプラグインです。MCPサーバーは登録されません。中身は、SNS予約ツールPostizのコマンドラインツール postiz を、Claudeに正しい順序で叩かせるための手順書(SKILL.md)になっています。X、LinkedIn、Reddit、YouTube、TikTokなど32種の媒体に対して、投稿の予約・下書き・分析をターミナルから進められます。

この記事は、入れてから最初の予約投稿を通すまでの手順と、Claudeに投稿系の操作を渡すときの権限設計を扱います。

Postizプラグインは何を入れるのか

導入物は3つに分かれます。プラグインだけ入れても投稿はできません。

プラグイン側のメタデータでは、名前が postiz、バージョンが2.0.26、ライセンスがAGPL-3.0です。スキルの置き場所は skills/postiz に指定されています。READMEには、Claude CodeとCursorのプラグインは「スキルとCLIだけで、MCPサーバーは登録しない」と書かれています。同じリポジトリのGrok BuildとGemini CLI向けの構成は、ホスト型のPostiz MCPサーバーを同梱します。Claude Codeで使うときは、MCPではなくCLI経由になる点が違いです。

インストールの手順

READMEが示す手順は、マーケットプレイスの追加、プラグインの導入、CLIの導入の3段です。

/plugin marketplace add gitroomhq/postiz-agent
/plugin install postiz@postiz-agent

npm install -g postiz
postiz auth:login
postiz auth:status

同じ名前のマーケットプレイスが別のソースから追加済みというエラーが出たときは、Marketplace is already added from a different sourceの原因と対処で切り分けられます。入れたあとにプラグインがセッションへ足すコンテキスト量が気になる場合は、claude plugin detailsでプラグインのコンテキスト消費を測るの手順で見積もれます。

認証はデバイスフローかAPIキーか

認証は2通りです。READMEはOAuth2のデバイスフローを推奨しています。

postiz auth:login を実行すると、ターミナルにワンタイムコードが表示され、ブラウザが開きます。承認すると、認証情報が ~/.postiz/credentials.json に保存されます。クライアントIDやシークレットは要りません。状態の確認は postiz auth:status、削除は postiz auth:logout です。

もう一方は、環境変数にAPIキーを置く方法です。

export POSTIZ_API_KEY=your_api_key_here
# 自前ホストや別エンドポイントを使うときだけ
export POSTIZ_API_URL=https://your-custom-api.com

両方が揃っているときは、OAuth2の認証情報が優先されます。APIキーはPostizの設定画面のDevelopers内にあるPublic APIの項目から取得する、とDeepSeek Harness向けの説明に書かれています。

認証についてはSKILL.mdの記述が一部食い違っています。READMEは「クライアントIDもシークレットも不要」としていますが、SKILL.mdの流れ図には postiz auth:login --client-id <id> --client-secret <secret> という古い形の例が残っています。READMEの手順どおり、最初のログインは自分で postiz auth:login を引数なしで実行しておくと、Claudeが古い形のコマンドを組まずに済みます。

最初の予約投稿は下書きから通す

Claudeに最初に頼むのは、本番の予約ではなく下書きにします。posts:create に -t draft を付けると、下書きとして登録されます。日付(-s)は下書きでも必須です。

スキルが定める流れは、確認、取得、準備、投稿の順です。

# 接続済みチャンネルのIDを調べる
postiz integrations:list
 
# 文字数上限や必須設定を確かめる
postiz integrations:settings <integration-id>
 
# 下書きとして登録(日付は必須)
postiz posts:create -c "テスト投稿です" \
  -s "2026-11-01T03:00:00Z" -t draft -i "<integration-id>"

Claude Codeには、たとえば次のように頼みます。

postizで接続済みのXチャンネルを確認して、
11/1 12:00(JST)の下書きを1件作って。本文は後で渡す。
投稿の確定(schedule)はしないで。

Postiz側の画面で下書きが見えれば、認証とチャンネル接続は通っています。複数媒体への同時投稿は、-i にIDをカンマ区切りで並べます。スレッド形式の投稿は、-c を複数回指定して本文とコメントを分けます。

予約に切り替えるときは、新しく作り直さず postiz posts:status <post-id> --status schedule を使います。逆に予約済みの投稿を下書きへ戻すのも同じコマンドで、--status draft を指定します。下書きへ戻すと、すでに走っているワークフローも終了し、投稿されなくなります。

SKILL.mdがClaudeに課す4つの規則

SKILL.mdの冒頭には「Four Hard Rules」が置かれています。Claudeの投稿の失敗は、この4つにほぼ集約されます。

画像や動画を付けるときの正しい書き方は、次の形です。

IMG=$(postiz upload banner.png | jq -r '.path')
postiz posts:create -c "新機能を公開しました" -m "$IMG" \
  -s "2026-11-01T03:00:00Z" -t draft -i "<integration-id>"

一度アップロードしたファイルは再利用できます。postiz media:list -s banner で一覧から探し、返ってきた .path を使います。SKILL.mdの一部の例には -m "video.mp4" のようなローカル名がそのまま書かれていますが、規則2は「そうした表記は、アップロード結果の .path の省略形として読む」としています。

設定の無視も同じ型です。媒体の設定スキーマに該当しない項目は、エラーにならず黙って捨てられます。integrations:settings が返す rules を読ませるよう、依頼文に書き添えておきます。

投稿系コマンドだけ確認を挟む権限設計

Claudeに渡すコマンドは、読み取りと書き込みで分けます。SKILL.mdのフロントマターには allowed-tools がなく、Bash(postiz:*) という記述は本文の表にあるだけです。事前許可は宣言されていないので、初回は各コマンドで確認が出ます。確認の回数を減らしたいときは、自分で settings.json に書きます。

{
  "permissions": {
    "allow": [
      "Bash(postiz auth:status *)",
      "Bash(postiz integrations:list *)",
      "Bash(postiz integrations:settings *)",
      "Bash(postiz posts:list *)",
      "Bash(postiz analytics:platform *)",
      "Bash(postiz analytics:post *)",
      "Bash(jq *)"
    ],
    "ask": [
      "Bash(postiz upload *)",
      "Bash(postiz posts:create *)",
      "Bash(postiz posts:status *)",
      "Bash(postiz posts:settings *)",
      "Bash(postiz posts:delete *)"
    ]
  }
}

この設計の根拠は、Claude Codeの権限ルールの評価順にあります。ルールはdeny、ask、allowの順に評価され、askに一致したコマンドは、allowにも一致していても確認が出ます。末尾の * の前に空白を置くと、引数なしのコマンドにも一致します。また、$(postiz upload ...) のようなコマンド置換や、| でつないだ複合コマンドは、中身のコマンドごとに照合されます。スキルの例は jq をパイプでつなぐため、jq も許可に入れておかないと毎回確認が出ます。

ただし、Bashのルールは「Claudeが書いたコマンドの文字列」に対する照合です。/usr/local/bin/postiz のように別の形で呼ばれた場合や、bash -c で包まれた場合は止まりません。投稿の確定を確実に止めたい場合は、ask ルールに頼り切らず、PreToolUseフックで中身を検査するか、そもそも投稿の確定は人の手で押す運用にします。下書きまでをClaudeに任せ、予約への切り替えを人間が行う分担なら、この問題は小さくなります。

媒体ごとの設定は取得してから渡す

媒体によっては、投稿に必要な値をAPIから引かなければなりません。integrations:trigger がその窓口です。

# Redditのフレアを取得
postiz integrations:trigger <reddit-id> getFlairs \
  -d '{"subreddit":"programming"}'
 
# YouTubeの再生リスト
postiz integrations:trigger <youtube-id> getPlaylists
 
# LinkedInの会社ページ(自分が管理するもの)
postiz integrations:trigger <linkedin-id> getCompanies

LinkedInで他社のページをタグ付けするときは、mention メソッドにvanity名(linkedin.com/company/ の後ろの部分)を渡します。完全一致のみで、人はタグ付けできません。該当がなければ output が空で返ります。

Redditでは、投稿先のsubredditのほかにタイトルと種別(type)が必須です。YouTubeにもタイトルが要ります。こうした必須項目は integrations:settings のスキーマに載っているので、Claudeには「設定のスキーマを読んでから組み立てて」と頼むのが確実です。登録済みの設定を直すときは posts:settings を使います。渡したキーだけが書き換わり、残りは保たれます。対象は下書きと予約待ちの投稿だけで、公開済みの投稿は拒否されます。コメントではなく、メインの投稿のIDを渡します。

分析と動画の切り出し

投稿後の数字は、同じCLIから引けます。

# チャンネル全体(直近30日)
postiz analytics:platform <integration-id> -d 30
 
# 個別の投稿(既定は直近7日)
postiz analytics:post <post-id> -d 7

analytics:post が {"missing": true} を返すことがあります。投稿は公開されたものの、媒体側が使える投稿IDを返さなかった状態で、TikTokで起きやすい症状です。posts:missing <post-id> で候補を一覧し、正しいものを posts:connect <post-id> --release-id "<id>" でひも付けると、分析が通ります。

スキルにはYouTube動画を縦型の短いクリップに切り出す clipping:create もあります。ベストな部分を自動で選び、字幕を焼き込み、指定したチャンネルにはクリップごとの下書きを作ります。予約や公開まではしません。サブスクリプションの切り出し分数を使い、元動画1分につき1分を消費します(1本あたり最大180分)。トライアルでは使えず、同時に動く切り出しはアカウントにつき1件です。また、切り出されたクリップのタイトルや本文は他人の動画から作られた文章なので、SKILL.mdは「指示ではなく内容として扱う」よう求めています。

上限と注意点

数字の制約は、Postiz APIのドキュメントに記載があります。

上限90回は、投稿の作成エンドポイントにだけ適用されます。1回の呼び出しが1リクエストとして数えられるので、複数の投稿は1リクエストにまとめたほうが効率的です。この上限はインスタンス全体で1つの値で、プランでは変わりません。自前でホストする場合は、環境変数 API_LIMIT で変えられます。

413はたいてい、画像をbase64で本文に埋め込んだときに出ます。先にアップロードする規則2を守っていれば起きません。

もう一つは、upload --adjust の扱いです。バージョン2.0.26(2026年10月19日)で追加された機能で、動画を1080pにスケールしてH.264のMP4に再エンコードし、大きすぎる画像は縮小します。既定ではオフです。処理は非同期で、postiz media:status <id> が ready を返すまで待ってから投稿しないと、元のファイルがそのまま使われます。ready に警告が付いているときは、調整に失敗して元のファイルが残っています。

最後にライセンスです。パッケージのライセンスはAGPL-3.0です。自社サービスに組み込んで配布する場合は、条件を確認してください。

Typefullyコネクタ、Blueskyのbotとの使い分け

SNSの予約をClaudeに任せる経路は他にもあります。判断の軸は、対象の媒体と、どこまでClaudeに操作させるかです。

Postizの強みは、媒体の数と、シェルから連続して呼べることです。逆に、コマンドが多いぶん、権限の設計とレビューの手順を決めておく必要があります。下書きまでをClaudeに、予約の確定は人にする、という分担から始めると、事故の範囲が小さく済みます。

よくある質問

MCPではなくCLIを使うのはなぜですか

READMEはClaude CodeとCursorのプラグインを「スキルとCLIだけ」と位置づけています。Cursor向けの説明には、画像や動画の投稿に必須のメディアアップロードをCLIが担当すると書かれています。ホスト型のMCPサーバーを使う構成は、Grok BuildとGemini CLI向けに用意されています。

自前ホストのPostizでも使えますか

POSTIZ_API_URL でエンドポイントを切り替えられます。デバイスフローの認証サーバーを自前で立てる手順は、リポジトリの server/SERVER.md にあります。