Storyblok Mcp Server

何ができるのか？

Storyblok MCP サーバーを使うと、AI アシスタントは次の操作を行えます。

• 作成 - 新しいストーリー、コンポーネント、アセット、データソース、タグ、リリース、ワークフローなどを作成します。
• 読み取り - すべてのストーリー、コンポーネント、アセット、データソース、タグ、リリース、ワークフローなどを読み取ります。
• 更新 - 既存または新規のストーリー、コンポーネント、アセット、データソース、タグ、リリース、ワークフローなどを更新します。
• 削除 - 特定またはすべてのストーリー、コンポーネント、アセット、データソース、タグ、リリース、ワークフローなどを削除します。

---

🚀 機能

• Storyblok の包括的な管理：ストーリー、コンポーネント、アセット、データソース、タグ、リリース、ワークフローなどの CRUD に対応しています（すべてを網羅）。
• モジュール式のツール構成：各 Storyblok リソースは専用のツールモジュールで管理されるため、簡単に拡張・保守できます。
• メタツール：実行時に利用可能なすべてのツールとその説明を確認できます。
• 非同期で高速：高いパフォーマンスを実現するため、httpx と FastMCP を基盤に構築されています。
• 環境変数による設定：.env を使用してトークンとスペース ID を安全に管理します。
• 一括操作：複数のリソースを一度に効率よく更新、削除、公開できます。

---

📦 プロジェクト構成

├── config.py              # Loads and validates environment config
├── server.py              # Main entrypoint, registers all tools
├── tools/                 # All modular tool implementations
│   ├── components.py      # Component CRUD and usage
│   ├── stories.py         # Story CRUD, bulk ops, validation
│   ├── ...                # (assets, tags, releases, workflows, etc.)
│   └── meta.py            # Meta tool for tool discovery
├── utils/
│   └── api.py             # API helpers, error handling, URL builders
├── .env                   # Your Storyblok tokens and space ID
├── pyproject.toml         # Python dependencies
└── README.md              # This file

---

🚀 API のカバレッジ

リソース	説明
アクセストークン	Storyblok API のアクセストークンを管理します
アクティビティ	アクティビティログを管理または取得します
承認	承認ワークフローを管理します
アセット	アセットを管理します（アップロード、更新、削除、一覧表示）
アセットフォルダー	アセットフォルダーを管理します
ブランチデプロイメント	ブランチデプロイメントを管理します
コラボレーター	スペース内のコラボレーターを管理します
コンポーネント	Storyblok コンポーネントを管理します（CRUD、スキーマなど）
コンポーネントフォルダー	コンポーネントのフォルダーを管理します
データソースエントリー	データソース内のエントリーを管理します
データソース	データソースを管理します（CRUD、エントリー）
ディスカッション	ディスカッションとコメントを管理します
拡張機能	Storyblok の拡張機能を管理します
フィールドプラグイン	カスタムフィールドプラグインを管理します
内部タグ	アセット／ストーリーの内部タグを管理します
メタ	メタツール：利用可能なすべてのツールを検出します
Ping	ヘルスチェックとサーバーのステータス
パイプライン	コンテンツ配信のパイプラインを管理します
プリセット	コンポーネントのフィールドプリセットを管理します
リリース	リリースを管理します（作成、更新、公開）
ストーリーのスケジュール設定	ストーリーの公開をスケジュール設定します
スペース	Storyblok のスペース設定と情報を管理します
スペースロール	スペース内のロールと権限を管理します
ストーリー	ストーリーを管理します（CRUD、一括操作、検証）
タグ	タグを管理します（CRUD、一括関連付け）
タスク	タスクを管理します（CRUD、Webhook、自動化）
Webhook	Webhook を管理します（CRUD、トリガー）
ワークフロー	ワークフローとワークフローステージを管理します
ワークフローステージ	個別のワークフローステージを管理します
ワークフローステージの変更	ワークフローステージの変更を追跡、管理します

---

🪄 利用可能なツール

アクセストークン

Storyblok API のアクセストークンを管理します

• retrieve_multiple_access_tokens: すべてのアクセストークンを一覧表示します
• create_access_token: 新しいアクセストークンを作成します
• update_access_token: 既存のアクセストークンを更新します
• delete_access_token: アクセストークンを削除します

アクティビティ

アクティビティログを管理または取得します

• retrieve_multiple_activities: アクティビティログを一覧表示します

承認

承認ワークフローを管理します

• retrieve_multiple_approvals: 承認を一覧表示します
• create_approval: 新しい承認を作成します
• update_approval: 承認を更新します
• delete_approval: 承認を削除します

アセット

アセットを管理します（アップロード、更新、削除、一覧表示）

• fetch_assets: フィルタリングしてアセットを一覧表示します
• get_asset: ID を指定して特定のアセットを取得します
• delete_asset: アセットを削除します
• update_asset: アセットを更新します
• delete_multiple_assets: 複数のアセットを削除します
• bulk_move_assets: 複数のアセットを移動します
• bulk_restore_assets: 複数のアセットを復元します
• init_asset_upload: アセットのアップロードを開始します
• complete_asset_upload: アセットのアップロードを完了します

### アセットフォルダー

アセットフォルダーを管理

• retrieve_multiple_asset_folders: アセットフォルダーの一覧を取得
• create_asset_folder: 新しいアセットフォルダーを作成
• update_asset_folder: アセットフォルダーを更新
• delete_asset_folder: アセットフォルダーを削除

ブランチデプロイメント

ブランチデプロイメントを管理

• retrieve_multiple_branch_deployments: ブランチデプロイメントの一覧を取得
• create_branch_deployment: 新しいブランチデプロイメントを作成
• update_branch_deployment: ブランチデプロイメントを更新
• delete_branch_deployment: ブランチデプロイメントを削除

コラボレーター

スペース内のコラボレーターを管理

• retrieve_multiple_collaborators: コラボレーターの一覧を取得
• add_collaborator: コラボレーターを追加
• update_collaborator: コラボレーターを更新
• remove_collaborator: コラボレーターを削除

コンポーネント

Storyblok コンポーネント（CRUD、スキーマなど）を管理

• fetch_components: フィルタリングしてコンポーネントの一覧を取得
• get_component: ID を指定してコンポーネントを取得
• create_component: 新しいコンポーネントを作成
• update_component: 既存のコンポーネントを更新
• delete_component: コンポーネントを削除
• get_component_usage: コンポーネントを使用しているストーリーを検索
• retrieve_component_versions: コンポーネントのバージョン一覧を取得
• retrieve_single_component_version: 特定のコンポーネントバージョンを取得
• restore_component_version: コンポーネントを以前のバージョンに復元

コンポーネントフォルダー

コンポーネント用のフォルダーを管理

• retrieve_multiple_component_folders: コンポーネントフォルダーの一覧を取得
• create_component_folder: 新しいコンポーネントフォルダーを作成
• update_component_folder: コンポーネントフォルダーを更新
• delete_component_folder: コンポーネントフォルダーを削除

データソースエントリー

データソース内のエントリーを管理

• retrieve_multiple_datasource_entries: データソースエントリーの一覧を取得
• create_datasource_entry: 新しいデータソースエントリーを作成
• update_datasource_entry: データソースエントリーを更新
• delete_datasource_entry: データソースエントリーを削除

データソース

データソース（CRUD、エントリー）を管理

• retrieve_multiple_data_sources: データソースの一覧を取得
• create_data_source: 新しいデータソースを作成
• update_data_source: データソースを更新
• delete_data_source: データソースを削除

ディスカッション

ディスカッションとコメントを管理

• retrieve_multiple_discussions: ディスカッションの一覧を取得
• retrieve_specific_discussion: 特定のディスカッションを取得
• retrieve_idea_discussions_comments: アイデアのディスカッションコメント一覧を取得
• create_discussion: 新しいディスカッションを作成
• retrieve_my_discussions: 自分のディスカッションの一覧を取得

拡張機能

Storyblok の拡張機能を管理

• retrieve_all_extensions: すべての拡張機能の一覧を取得
• retrieve_extension: 特定の拡張機能を取得
• create_extension: 新しい拡張機能を作成
• update_extension: 拡張機能を更新
• delete_extension: 拡張機能を削除
• retrieve_extension_settings: 拡張機能の設定を取得
• retrieve_all_extension_settings: すべての拡張機能設定の一覧を取得

フィールドプラグイン

カスタムフィールドプラグインを管理

• retrieve_field_plugins: フィールドプラグインの一覧を取得
• retrieve_field_plugin: 特定のフィールドプラグインを取得
• create_field_plugin: 新しいフィールドプラグインを作成
• update_field_plugin: フィールドプラグインを更新
• delete_field_plugin: フィールドプラグインを削除

内部タグ

アセット／ストーリーの内部タグを管理

• retrieve_multiple_internal_tags: 内部タグの一覧を取得
• create_internal_tag: 新しい内部タグを作成
• update_internal_tag: 内部タグを更新
• delete_internal_tag: 内部タグを削除

### Meta

Meta ツール：利用可能なすべてのツールを確認

• list_tools：利用可能なすべてのツールを一覧表示

Ping

ヘルスチェックとサーバーのステータス

• ping：サーバーの状態を確認

Pipelines

コンテンツ配信用のパイプラインを管理

• retrieve_multiple_branches：ブランチを一覧表示
• retrieve_single_branch：特定のブランチを取得
• create_branch：新しいブランチを作成
• update_branch：ブランチを更新
• delete_branch：ブランチを削除

Presets

コンポーネントのフィールドプリセットを管理

• retrieve_multiple_presets：フィールドプリセットを一覧表示
• retrieve_single_preset：特定のプリセットを取得
• create_preset：新しいプリセットを作成
• update_preset：プリセットを更新
• delete_preset：プリセットを削除

Releases

リリースを管理（作成、更新、公開）

• retrieve_multiple_releases：リリースを一覧表示
• retrieve_single_release：特定のリリースを取得
• create_release：新しいリリースを作成
• update_release：リリースを更新
• delete_release：リリースを削除

Scheduling Stories

ストーリーの公開スケジュールを設定

• retrieve_multiple_story_schedules：ストーリーのスケジュールを一覧表示
• retrieve_one_story_schedule：特定のストーリーのスケジュールを取得
• create_story_schedule：新しいストーリーのスケジュールを作成
• update_story_schedule：ストーリーのスケジュールを更新
• delete_story_schedule：ストーリーのスケジュールを削除

Space

Storyblok のスペース設定と情報を管理

• fetch_spaces：スペースを一覧表示
• get_space：特定のスペースを取得
• create_space：新しいスペースを作成
• update_space：スペースを更新
• duplicate_space：スペースを複製
• backup_space：スペースをバックアップ
• delete_space：スペースを削除

Space Roles

スペース内のロールと権限を管理

• fetch_space_roles：スペースのロールを一覧表示
• get_space_role：特定のスペースロールを取得
• create_space_role：新しいスペースロールを作成
• update_space_role：スペースロールを更新
• delete_space_role：スペースロールを削除

Stories

ストーリーを管理（CRUD、一括操作、検証）

• fetch_stories：フィルタリングしてストーリーを一覧表示
• get_story：ID を指定して特定のストーリーを取得
• create_story：新しいストーリーを作成
• update_story：既存のストーリーを更新
• delete_story：ストーリーを削除
• publish_story：ストーリーを公開
• unpublish_story：ストーリーの公開を取り消し
• get_story_versions：ストーリーのバージョンを一覧表示
• restore_story：ストーリーを以前のバージョンに復元
• validate_story_content：ストーリーのコンテンツを検証
• debug_story_access：ストーリーへのアクセスをデバッグ
• bulk_publish_stories：複数のストーリーを公開
• bulk_delete_stories：複数のストーリーを削除
• bulk_update_stories：複数のストーリーを更新
• bulk_create_stories：複数のストーリーを作成
• get_unpublished_dependencies：未公開の依存関係を一覧表示
• ai_translate_story：AI によるストーリーの翻訳
• compare_story_versions：ストーリーの2つのバージョンを比較

Tags

タグを管理（CRUD、一括関連付け）

• retrieve_multiple_tags：タグを一覧表示
• create_tag：新しいタグを作成
• update_tag：タグを更新
• delete_tag：タグを削除
• tag_bulk_association：複数のストーリーにタグを追加

Tasks

タスクを管理（CRUD、Webhook、自動化）

• retrieve_multiple_tasks：タスクを一覧表示
• retrieve_single_task：特定のタスクを取得
• create_task：新しいタスクを作成
• update_task：タスクを更新
• delete_task：タスクを削除

### Webhooks

ウェブフックを管理（CRUD、トリガー）

• retrieve_multiple_webhooks: ウェブフックの一覧を取得
• retrieve_single_webhook: 特定のウェブフックを取得
• add_webhook: 新しいウェブフックを追加
• update_webhook: ウェブフックを更新
• delete_webhook: ウェブフックを削除

ワークフロー

ワークフローとワークフローのステージを管理

• retrieve_multiple_workflows: ワークフローの一覧を取得
• retrieve_single_workflow: 特定のワークフローを取得
• create_workflow: 新しいワークフローを作成
• update_workflow: ワークフローを更新
• duplicate_workflow: ワークフローを複製
• delete_workflow: ワークフローを削除

ワークフローのステージ

個々のワークフローのステージを管理

• retrieve_multiple_workflow_stages: ワークフローのステージ一覧を取得
• retrieve_single_workflow_stage: 特定のワークフローのステージを取得
• create_workflow_stage: 新しいワークフローのステージを作成
• update_workflow_stage: ワークフローのステージを更新
• delete_workflow_stage: ワークフローのステージを削除

ワークフローのステージ変更

ワークフローのステージ変更を追跡、管理

• retrieve_multiple_workflow_stage_changes: ワークフローのステージ変更一覧を取得
• create_workflow_stage_change: ワークフローのステージ変更を作成

⚡️ クイックスタート

1. リポジトリをクローン

   git clone <your-repo-url>
   cd storyblok-mcp-server
   

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

   pip install -r requirements.txt
   

3. 環境を設定

   • .env.example を .env にコピーし、Storyblok の認証情報を入力します：

     STORYBLOK_SPACE_ID=your_space_id
     STORYBLOK_MANAGEMENT_TOKEN=your_management_token
     STORYBLOK_DEFAULT_PUBLIC_TOKEN=your_public_token
     

4. MCP クライアントの設定

   • このサーバーを Claude または任意の MCP クライアントで使用するには、以下を claude_desktop_config.json にコピーします：

{
    "mcpServers": {
        "storyblok": {
            "command": "uv",
            "args": [
                "run",
                "--with",
                "mcp",
                "mcp",
                "run",
                "C:\\path\\to\\storyblok-mcp-server\\server.py"
            ],
            "env": {
                "STORYBLOK_SPACE_ID": "your_space_id",
                "STORYBLOK_MANAGEMENT_TOKEN": "your_management_token",
                "STORYBLOK_DEFAULT_PUBLIC_TOKEN": "your_public_token"
            }
        }
    }
}

• この設定を Claude または MCP クライアントに貼り付けると、すぐに接続できます。

メモ

システムに uv がインストールされていることを確認してください

Claude Desktop を再起動して、ツールを確認してください。正常に接続されると、利用可能なツールの合計数が表示されます。

5. ローカルで実行してテスト
   • MCP Inspector を使って、サーバーをローカルで実行してテストすることもできます：

   mcp run server.py
   

質問の例

ヒント

MCP クライアントで試せる自然言語のクエリを紹介します。

• 「Storyblok のすべてのストーリーを表示して」
• 「Home ストーリーの詳細を教えて」
• 「任意のコンテンツで新しいストーリーを作成して」
• 「Home ストーリーを公開して」

---

🧑‍💻 コントリビューション

コントリビューションを歓迎します！始めるには：

1. リポジトリをフォークし、master からブランチを作成します。
2. tools/ ディレクトリでツールを追加または改善します。
3. わかりやすい docstring を記述し、コードをモジュール化します。
4. デバッグには MCP Inspector を使用します
5. 変更内容を明確に説明してプルリクエストを作成します。

コーディングガイドライン

• すべての関数とクラスに型ヒントと docstring を使用します。
• 各ツールは、単一の Storyblok リソースに特化させます。
• API エラーを適切に処理し、わかりやすいメッセージを返します。
• .env ファイルをバージョン管理の対象に含めないでください。

---

🤝 クレジット

Storyblok と FastMCP を使用して構築されています。

---

📄 ライセンス

MIT ライセンスです。詳細は LICENSE を参照してください。

---

💬 質問とサポート

• 問題を報告するには、GitHub issue を作成してください。
• 機能をリクエストするには、ディスカッションを開始するか、PR を作成してください。
• Storyblok API のドキュメントは、Storyblok API リファレンスを参照してください。

---

Kiran が 💙 を込めて作成