Markaestro

@markaestro/mcp

AI エージェント（Claude Code、Claude、Cursor、ChatGPT、Grok、Grok Bot、OpenClaw、Hermes、その他すべての MCP クライアント）が、公開 API を通じて Markaestro の投稿を予約、公開、確認できる Model Context Protocol サーバーです。各クライアントの正確な接続手順は https://markaestro.com/developers/agents にあります（?client=cursor、chatgpt、grok、grok-bot、openclaw、hermes、headless を指定すると、それぞれのタブが開きます）。

各キーは、キーの作成時またはサインイン時の同意画面で選択した、1つのブランドまたはワークスペース内のすべてのブランドを対象とします。単一ブランドのキーは、そのブランドだけで機能します。全ブランド対応のキーではすべてのブランドを利用できます。list_products はそれらすべてを返し、エージェントは create_post、create_posts、list_posts、create_evergreen_queue、および分析ツールに productId を渡すことで、ワークスペース全体ではなく1つのブランドを対象にレポートできます。

ツール

ツール	機能
list_products	このキーで操作できるブランド（1つ、またはワークスペース内のすべて）と、接続済みのチャネル
list_destinations	ブランドの公開可能な投稿先（ページ、アカウント）とその ID
get_brand_profile	ブランドの説明、トーン、ビジュアルアイデンティティ（読み取り専用）
list_posts, get_post	ステータスで投稿を読み込み、cursor を使ってページを移動します
create_post	下書きを保存します。scheduledAt を設定すると予約投稿になります
update_post	下書きまたは予約投稿のキャプション、メディア、1つのチャネルの設定、または投稿時刻を編集します
publish_post	即時公開のキューに追加し、ジョブ実行を返します
mark_post_posted	手動リマインダーまたは TikTok インボックスの投稿を、人が投稿したこととして記録します
delete_post	下書きを削除するか、いずれかのプラットフォームに到達する前の投稿をキャンセルします。公開済みの投稿は拒否されます
bulk_posts	最大25件の投稿を再予約またはステータス変更します
create_posts	1回の呼び出しで最大25件の投稿を作成し、アイテムごとの結果を返します
upload_media	ファイルパス、URL、またはデータ URL からアップロードし、アセット ID を返します
list_media, get_media	アップロード済みアセット、処理状態、参照数
get_analytics	期間内のブランドのパフォーマンス：合計、チャネル、日別の推移、人気の投稿、ヒートマップ、インサイト。Markaestro 経由で公開された投稿と、プラットフォーム上で直接公開された投稿が対象です
list_post_analytics	期間内のすべての投稿について、最新の指標とソースを表示します。閲覧数、リーチ、エンゲージメント、またはエンゲージメント率で並べ替えられます
get_post_analytics_history	1件の投稿について、1時間から90日までの指標スナップショットと、各段階間の増加量を取得します
refresh_analytics	プラットフォームから最新の指標を取得します（1分あたり数回）
suggest_post_times	ブランド自身の履歴から学習した、ブランドに最適な投稿時間帯
get_job_run, list_job_runs	公開処理が成功または失敗するまで追跡します
get_channel_rules	チャネルごとのメディア、キャプション、配信モードのルール
get_tiktok_posting_options	Direct Post に必要な、TikTok クリエイターの現在のプライバシーレベルとインタラクション設定

Evergreen ツール（preview_、create_、get_、list_、update_、 activate_、pause_、resume_evergreen_queue、list_evergreen_runs、 get_evergreen_analytics）は、実績のある定期コンテンツを管理します。

エージェントが管理するのはソーシャルメディアのみです。アカウント設定、 請求、チーム、API キー、Webhook、チャネル接続は公開されていません。 また、公開済みの投稿を削除したり、プラットフォームから取り下げたり、 Evergreen キューをアーカイブしたりするツールはありません。これらの操作は Markaestro でユーザーが行います。同じルールは REST レイヤーにも適用されます。 エージェントのサインインを通じて発行されたキーでは、公開済みの投稿の削除、 プラットフォームからの取り下げ、Webhook の管理はできません （FORBIDDEN_AGENT_CONNECTION）。ユーザーが Settings で発行したキーでは、 そのスコープで許可されている REST の全機能を引き続き利用できます。

また、markaestro://channel-rules リソースと、安全な予約投稿の手順を エージェントに案内する schedule_post プロンプトも提供しています。

投稿は下書きが先です。scheduledAt を指定せずに create_post を実行しても 公開されることはありません。今すぐ公開できるツールは publish_post のみで、 その説明では、まずユーザーに確認するようエージェントに指示しています。

接続方法は 2 つあります

ホステッド（インストールも貼り付けも不要）。 Markaestro は、Streamable HTTP を通じて同じツールを https://markaestro.com/api/public/v1/mcp で提供します。認証情報なしで追加でき、最初のツール呼び出しでブラウザーが開きます。サインインして、ワークスペースとブランドを選び、「許可」をクリックしてください。クライアントはそのブランドに紐付けられた API キーを受け取り、独自に更新します。

claude mcp add --transport http markaestro https://markaestro.com/api/public/v1/mcp

これは標準的な OAuth 2.1（PKCE、動的クライアント登録、/.well-known/oauth-protected-resource および /.well-known/oauth-authorization-server でのディスカバリー）を使用しているため、claude.ai、Cursor、その他の MCP クライアントも同じ方法で接続できます。接続済みのエージェントは、「設定」内の「API」で一覧表示および取り消しができます。

ヘッドレス環境や CI で使用する場合は、代わりにワークスペースの API キーをベアラーヘッダーとして渡してください。

claude mcp add --transport http markaestro https://markaestro.com/api/public/v1/mcp \
  --header "Authorization: Bearer mk_live_..."

{
  "mcpServers": {
    "markaestro": {
      "type": "http",
      "url": "https://markaestro.com/api/public/v1/mcp",
      "headers": { "Authorization": "Bearer mk_live_..." }
    }
  }
}

読み取りツールのみを利用するには、追加のヘッダーとして x-markaestro-read-only: 1 を送信してください。

ローカルパッケージ。 サーバーを stdio 経由でマシン上で実行します。これにより、upload_media でローカルファイルを読み取ることもできます。

セットアップ

1. Markaestro の「設定」>「API アクセス」で API キーを作成します。ブランドと、エージェントに必要なスコープ（products.read、posts.read、posts.write、media.write、公開する可能性がある場合は posts.publish）を選び、評価中はテストキーを使用してください。
2. MARKAESTRO_API_KEY を通じて、サーバーにキーを渡します。

Claude Code

claude mcp add markaestro -e MARKAESTRO_API_KEY=mk_live_... -- npx -y @markaestro/mcp

Claude Desktop、Cursor、その他の JSON 設定

{
  "mcpServers": {
    "markaestro": {
      "command": "npx",
      "args": ["-y", "@markaestro/mcp"],
      "env": { "MARKAESTRO_API_KEY": "mk_live_..." }
    }
  }
}

環境変数

変数	必須	デフォルト
MARKAESTRO_API_KEY	はい	n/a
MARKAESTRO_BASE_URL	いいえ	https://markaestro.com
MARKAESTRO_READ_ONLY	いいえ	未設定。1 を指定すると読み取りツールのみを登録します

サーバーが代わりに行うこと

• すべての変更リクエストに、呼び出しごとに一度だけ生成する Idempotency-Key を付与します。そのため、リクエストを再試行しても二重投稿されず、前回の結果が返されます。
• サーバーの Retry-After に従って、429 および一時的な 5xx レスポンスを再試行します。
• 3 段階の直接メディアアップロード（セッション作成、ストレージへの PUT、確定）を実行し、API キーをストレージ URL に送信しません。
• API の失敗をツールエラーとして返します。安定したエラー code、チャンネルごとの issues（存在する場合）、変更内容に関するヒントが含まれます。

Claude Code プラグイン

スキルとホステッドサーバーは、プラグインとして一緒に提供されます。

claude plugin marketplace add markaestro/markaestro-agents
claude plugin install markaestro@markaestro

デプロイ

メンテナー向け：すべての提供先、バージョンファイル、正確なコマンドを記載したリリース手順書は、Markaestro アプリのリポジトリにある docs/operations/mcp-release.md です。概要：

提供先	公開方法
ホステッド MCP（/api/public/v1/mcp）	Next.js アプリの一部です。他のすべてのルートと同様に、main へのプッシュ時にデプロイされます
npm の @markaestro/mcp	cd mcp && npm version <x.y.z> && npm publish（公開スコープ付きパッケージ。prepublishOnly でビルドされます）。同時に src/version.ts も更新します
プラグインとスキル	node scripts/sync-agents-repo.mjs <clone> で公開リポジトリ markaestro/markaestro-agents にミラーリングし、そこでプッシュします。claude plugin marketplace add markaestro/markaestro-agents で読み込みます。スキルだけなら ~/.claude/skills/markaestro にコピーできます
MCP Registry（com.markaestro/mcp）	同じバージョンの npm パッケージを公開した後、mcp/ から mcp-publisher login http --domain markaestro.com --private-key <hex> を実行し、続けて mcp-publisher publish を実行します。公開鍵は /.well-known/mcp-registry-auth で提供されます
Glama（markaestro/markaestro-agents）	管理画面の Dockerfile で、ビルド手順に npm install -g @markaestro/mcp@<version>、CMD に markaestro-mcp を設定します。「Build」を実行してから「Create Release」を選びます

開発

cd mcp
npm install
npm run build
MARKAESTRO_API_KEY=mk_test_... MARKAESTRO_BASE_URL=http://localhost:3000 npm run smoke            # local stdio
MARKAESTRO_API_KEY=mk_test_... MARKAESTRO_BASE_URL=http://localhost:3000 npm run smoke -- --remote # hosted endpoint

ユニットテストは src/__tests__ にあり、リポジトリの npm test で実行できます。 スモークテスト用スクリプトは、ビルド済みサーバーを stdio 経由で起動し、ツールの一覧表示、ブランドの読み取り、下書きの作成と再読み込み、削除を行います。公開は行われません。