FastMCP server for Substack — publish Notes and posts, pull analytics, manage dr

substack-mcp

Substack 用の FastMCP サーバーです。Notes や投稿の公開、分析データの取得、下書きの管理、Obsidian のボルト内の下書きと Substack の連携、プラグイン式画像生成ツールによるビジュアルカードの作成ができます。

クイックリファレンス

substack__test_connection             -- verify auth (start here)
substack__publish_note text=...       -- publish a Note immediately
substack__list_vault_drafts           -- show drafts from your vault file
substack__publish_vault_draft index=N -- publish one vault draft as a Note
substack__create_draft title=... body=... -- create a post draft
substack__get_dashboard days=30       -- subscriber + view KPIs
substack__capture_analytics_to_vault  -- snapshot analytics to vault markdown

ツール一覧（30）

Notes とボルトのワークフロー

• test_connection(publication?) -- 認証を確認し、プロフィールを返します
• list_publications() -- 設定済みの出版物と、デフォルトの出版物を表示します
• publish_note(text, publication?, attachment_ids?) -- Note をすぐに公開します。Markdown に対応しています
• create_note_attachment(image_path?, image_url?, link_url?, publication?) -- 画像をアップロードするか、リンクを登録します。publish_note で使用する添付ファイルの UUID を返します
• list_my_notes(limit?, publication?) -- 最近の自分の Notes を、リアクション数とコメント数とともに表示します
• reply_to_note(note_id, text, publication?) -- ID で指定した Note に返信します
• list_vault_drafts() -- ボルトの下書きファイルを解析し、各下書きのインデックスとプレビューを返します
• publish_vault_draft(index, publication?, move_to_published?) -- ボルト内の下書きを 1 件 Note として公開します
• batch_publish_vault_drafts(indices, publication?) -- 複数のボルト内の下書きを順番に公開します

投稿の管理

• create_draft(title, body, subtitle?, audience?, publication?, section_id?) -- 投稿の下書きを作成します。本文は Markdown です
• update_draft(draft_id, title?, body?, subtitle?, audience?, publication?, section_id?) -- 既存の下書きを編集します
• publish_post(draft_id, send_email?, audience?, publication?, section_id?) -- 下書きを公開し、購読者が閲覧できるようにします
• schedule_post(draft_id, publish_at, publication?, section_id?) -- 下書きの公開を予約します（ISO 8601）
• list_sections(publication?) -- 出版物に設定されたセクションを一覧表示します。セクションのある出版物で公開するには必須です
• list_drafts(limit?, publication?) -- 未公開の下書きを一覧表示します
• list_published(limit?, publication?) -- 公開済みの投稿と基本的な統計情報を一覧表示します
• get_post(identifier, publication?) -- スラッグまたは数値 ID で投稿の全文を取得します
• upload_image(image_path, publication?) -- Substack CDN に画像をアップロードし、CDN URL を返します
• react(post_id, publication?) -- 投稿にハートを付けます
• restack(post_id, publication?) -- 投稿を restack します
• comment(post_id, body, publication?) -- 投稿にコメントします
• get_feed(limit?, publication?) -- 自分のフィードを取得します（フォローしている出版物の投稿）

アナリティクス

• get_dashboard(days?, publication?) -- KPI：購読者数（合計／有料）、閲覧数、成長率、ARR
• get_post_stats(post_id, publication?) -- 1つの投稿の閲覧数、開封数、クリック数、シェア数、コンバージョン数
• get_subscriber_growth(publication?) -- 時系列での購読者数
• get_growth_sources(publication?) -- ソース（検索、レコメンデーション、ダイレクト、ソーシャル）別の購読者増加数
• get_top_posts(limit?, publication?) -- エンゲージメント順に並べた投稿
• get_earnings(publication?) -- 有料出版物の収益データ
• get_recommendation_stats(direction?, publication?) -- レコメンデーションネットワークのパフォーマンス
• capture_analytics_to_vault(publication?) -- 週次アナリティクスのスナップショットをボルトに書き込みます

インストール

Claude Codeを開き、次の内容を貼り付けます。

/plugin marketplace add adelaidasofia/substack-mcp
/plugin install substack-mcp@substack-mcp

git clone https://github.com/adelaidasofia/substack-mcp
cd substack-mcp
pip3 install -r requirements.txt
python3 -c "import server; print('OK')"

設定

config.example.jsonをconfig.jsonにコピーし、値を入力します。

cp config.example.json config.json

config.jsonはgitignoreに登録されています。主なフィールドは次のとおりです。

セッションCookieの設定

SubstackにはOAuthを使う公開APIがありません。認証にはブラウザーのセッションCookieを使用します。

1. Chromeを開き、Substackにログインします。
2. DevTools（F12）を開き、Applicationタブに移動します。
3. Cookiesの下にあるsubstack.comを見つけます。
4. substack.sidの値をコピーします。
5. config.jsonの該当する出版物のcookieフィールドに貼り付けます。

値をそのまま使用できます。サーバーはabc123とsubstack.sid=abc123の両方を受け付けます。

セッションCookieには有効期限があります。ツールが{"error": "Auth failed"}を返す場合は、Cookieを再取得してください。

Claude Codeへの登録

プロジェクト単位の.mcp.jsonに追加するか、claude mcp add -s userで追加します。

{
  "mcpServers": {
    "substack": {
      "command": "python3",
      "args": ["/path/to/substack-mcp/server.py"]
    }
  }
}

.mcp.jsonを編集した後、Claude Codeを再起動します。claude mcp listで確認してください。

ボルトとの連携

config.jsonのvault_drafts_pathに、Obsidianボルト内のMarkdownファイルを設定します。 各下書きは、---で区切られたセクションとして記述します。## Ready to Postの下にあるセクションは、list_vault_draftsで最初に表示されます。次に## Essay Seedsの下にあるセクションが表示されます。

公開後、publish_vault_draftは下書きを## Publishedセクションに移動し、SubstackのURLとタイムスタンプを追記します。

交換可能な画像ジェネレーター

ビジュアルカードの生成には、config.jsonのimage_generator.defaultで設定したアダプターを使用します。

同梱アダプター

pillow_local（デフォルト）-- 外部APIを使わず、Pillowのみで処理します。fonts/ディレクトリのフォントを使って、1080x1080のPNGカードをローカルで描画します。テンプレートは3種類です。オプションで人物を追加できる温かみのあるマスタード色（P1）、深いバーガンディ色の太字引用（P2）、セクションタグ付きのマスタード色（P3）です。スタンドアロンのCLIとしてrender_card.pyと併用できます。

canva -- Canva MCPの連携処理です。テンプレートの複製、テキストの置換、人物の差し替え、PNGのエクスポートに必要なCanva MCPツール呼び出しを記述したstepsリストを返します。プレイブックを実行するClaudeセッションは、これらの手順に従います。Claude CodeにCanva MCPが接続されており、image_generator.canva.pillarsにデザインIDが入力されている必要があります。

スタブ化されたアダプター（貢献歓迎）

nano_banana — nano-banana スキル経由の Gemini 3 Pro Image。image_generators/nano_banana.py にスタブがあります。カード仕様からプロンプトを組み立て、スキルの画像エンドポイントを呼び出すように generate() を実装してください。

midjourney — Midjourney API（またはプロキシ）。image_generators/midjourney.py にスタブがあります。プロンプトを送信し、完了するまでポーリングして、結果をダウンロードするように generate() を実装してください。

dalle — OpenAI DALL-E。image_generators/dalle.py にスタブがあります。openai.images.generate を使用して generate() を実装してください。

独自のアダプターを作成する

image_generators.base の ImageGenerator をサブクラス化します。

from image_generators.base import ImageGenerator

class MyAdapter(ImageGenerator):
    @property
    def name(self) -> str:
        return "my_adapter"

    def generate(self, spec: dict) -> dict:
        # spec keys: pillar, quote, handle, figure_path, output_path
        # return: {status: "ok", adapter: ..., image_path: ..., width: ..., height: ...}
        ...

image_generators/__init__.py に登録し、config.json の image_generator.my_adapter の下に設定ブロックを追加します。

ビジュアル公開パイプライン

visual_helper.py スクリプトは、ビジュアルキューパイプラインの決定論的な処理を担います。Review Queue の Markdown ファイルの解析、図の順次処理、エントリーの公開済みマーク付けを行います。画像生成、アップロード、公開の手順を含むエンドツーエンドのフロー全体については、visual_playbook.md を参照してください。

python3 visual_helper.py peek --lang es        # get next approved visual item
python3 visual_helper.py mark --lang es ...    # mark published + update log
python3 visual_helper.py rotate-figure --pillar P1

既知の注意点

1. Cookie の有効期限。 substack.sid Cookie は数週間で期限切れになります。test_connection が認証エラーを返す場合は、Chrome DevTools から再抽出してください。

2. draft_bylines は必須ですが、ドキュメントに記載されていません。 create_draft はこれがないと 400 を返します。サーバーは /user/profile/self から user_id を自動取得し、すべてのドラフト POST に挿入します。

3. ノート添付エンドポイントには末尾のスラッシュが必要です。 POST /comment/attachment/（スラッシュあり）は機能します。スラッシュがない場合は 404 を返します。サーバーはこれを正しく処理します。

4. パブリケーションのスコープ付きエンドポイントとグローバルエンドポイント。 ノートには substack.com/api/v1/comment/feed/ を使用します。投稿ドラフトには {subdomain}.substack.com/api/v1/drafts を使用します。これらを混在させると 404 または 403 が返されます。

5. ダッシュボードの pledgedArr は実際の誓約ではなく、投影値です。 実際の収益データには get_earnings を使用してください。

6. 複数のパブリケーションへの対応。 特定のパブリケーションを対象にするには、任意のツールに publication="name" を渡します。省略すると、設定の default_publication が使用されます。

7. セクションがあるパブリケーションで公開するには、セクションの指定が必要です。 ドラフトがセクションに分類されていない場合、Substack は publish_post / schedule_post に対して HTTP 400: Please choose a section を返します。list_sections(publication="main") でセクション ID を調べてから、ドラフトツールまたは公開／予約ツールのいずれかに section_id=<id> を渡してください。

   list_sections                             # → [{id: 12345, name: "Essays", slug: "essays", ...}, ...]
   create_draft title=... body=... section_id=12345
   # or, for an existing draft:
   publish_post draft_id=987654 section_id=12345
   

publish_post / schedule_post は公開前にドラフトを更新するため、呼び出しは 1 回で十分です。

関連する MCP

同じ著者、同じアーキテクチャパターン（FastMCP、該当する書き込みではドラフト＋確認、Vault の自動エクスポート、MIT）：

• slack-mcp — 複数ワークスペースの Slack
• imessage-mcp — macOS の iMessage
• whatsapp-mcp — whatsmeow 経由の WhatsApp
• google-workspace-mcp — Gmail / Calendar / Drive / Docs / Sheets
• apollo-mcp — Apollo.io CRM ＋ シーケンス
• luma-mcp — lu.ma のイベント
• parse-mcp — markitdown / Docling / LlamaParse ルーター
• rescuetime-mcp — RescueTime の生産性データ
• graph-query-mcp — Vault のナレッジグラフクエリ
• graph-autotagger-mcp — グラフからのウィキリンク候補
• investor-relations-mcp — シード調達パイプラインのトラッカー
• vault-sync-mcp — Vault の双方向同期

テレメトリー

このプラグインは、特定のマシンで Claude Code セッションに初めて読み込まれたときに、myceliumai.co に匿名のインストールシグナルを 1 回送信します。

送信される情報：

• プラグイン名（例：slack-mcp）
• プラグインのバージョン（例：0.1.0）

送信されない情報：

• ユーザー識別子、名前、メールアドレス、トークン、API キーは送信されません
• ファイルパス、メッセージ内容、作業に関する情報は送信されません
• 重複排除処理後、IP アドレスは保存されません

目的： ユーザーが実際にインストールするプラグインをメンテナーが把握し、よく使われているプラグインに注力できるようにします。

オプトアウト： Claude Code の起動前に、環境変数 MYCELIUM_NO_PING=1 を設定してください。フックはネットワーク呼び出しを完全にスキップします。すでにシグナルを送信済みのインストールでは、~/.mycelium/onboarded-<plugin> にセンチネルファイルが作成されます。状態をリセットする場合は、このファイルを削除してください。

ライセンス

MIT

Mycelium AI が開発しました。フルインストールまたはチーム向けバージョンは diazroa.com をご覧ください。