Umbraco-CMS-MCP-Dev

Umbraco MCP

Umbraco CMS 用の MCP（Model Context Protocol）サーバーです。AI を活用したコンテンツ管理を実現します。Umbraco Management API に包括的にアクセスできるため、AI エージェントが自然な会話を通じてバックオフィスのタスクを実行できます。UI を操作する必要がなくなり、手動では面倒、あるいは不可能な複雑で反復的なワークフローも、簡単に実行できるようになります。

はじめに

MCP サーバーは Umbraco API ユーザーを使って認証し、Umbraco Management API への安全な権限ベースのアクセスを実現します。つまり、Umbraco の標準的なユーザー権限システムを通じて、AI エージェントが実行できる操作を完全に制御できます。特別なセキュリティモデルは必要ありません。

クイックスタート

1. Umbraco API ユーザーを作成する

まず、適切な権限を持つ Umbraco API ユーザーを作成します。手順については、Umbraco のドキュメントをご覧ください。

2. Claude Desktop にインストールする

Claude Desktop アプリをダウンロードしてインストールし、MCP サーバーを設定に追加します。

1. Claude Desktop の「設定」>「開発者」>「設定を編集」を開きます
2. 次の設定を claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "umbraco-mcp": {
      "command": "npx",
      "args": ["@umbraco-cms/mcp-dev@17"],
      "env": {
        "NODE_TLS_REJECT_UNAUTHORIZED": "0",
        "UMBRACO_CLIENT_ID": "your-api-user-id",
        "UMBRACO_CLIENT_SECRET": "your-api-secret",
        "UMBRACO_BASE_URL": "https://localhost:{port}",
        "UMBRACO_INCLUDE_TOOL_COLLECTIONS": "document,media,document-type,data-type"
      }
    }
  }
}

3. Claude Desktop を完全に再起動します（Windows の場合はシステムトレイ内も含みます）。

ヒント： @latest ではなく、サイトの Umbraco のメジャーバージョンに @umbraco-cms/mcp-dev を固定してください（例：上記の @17、または Umbraco 18.x のサイトなら @18）。ツールのスキーマはパッケージ自身のメジャーバージョンに対応する Management API に基づいているため、メジャーバージョンが一致しないと、ツールの構造が変わった際にタスクの途中で予期しないエラーが発生することがあります。サーバーは起動時に接続先サイトのバージョンを確認し、不一致の場合は警告しますが、バージョンを固定すれば問題を未然に防げます。

ドキュメント

インストール手順、設定オプション、ツール一覧、使用例については、完全なドキュメントをご覧ください。

Umbraco MCP ドキュメント

ホステッドデプロイ

Cloudflare Worker のエントリーポイント（src/worker.ts）は、@umbraco-cms/mcp-hosted ライブラリによってリクエスト時に選択される、2 つのデプロイモードに対応しています。

• シングルテナント（デフォルト） — Worker は wrangler.toml で設定された UMBRACO_BASE_URL を使用して認証します。これは既存の動作であり、追加の設定は不要です。
• マルチテナントの Umbraco Cloud — wrangler.toml の [vars] で UMBRACO_CLOUD_ROUTING_ENABLED = "true" を設定します。/at/{alias}/... へのリクエストは {alias} に対応する Umbraco Cloud プロジェクトを解決し、MCP resource-indicator 仕様に従って、そのリソースにスコープされたアクセストークンを発行します。Worker が提供する Umbraco Cloud プロジェクトごとに、ID が umbraco-cms-developer-mcp-hosted の OpenIddict クライアントを登録する必要があります。

siteRouting は常に設定されます。リクエストごとの切り替えは環境変数で行います。

AI ツールを活用した貢献

このプロジェクトは、AI コーディングアシスタントを利用した開発に最適化されています。既存のパターンやテスト標準を一貫して維持できるよう、広く使われている AI ツール向けの指示ファイルを用意しています。

rulesync を使用する

このプロジェクトには、19 以上の AI 開発ツール向けの指示ファイルを自動生成できる rulesync 設定ファイルが含まれています。利用する AI ツールに合わせて設定ファイルを生成します。

# Generate only for Claude Code
npx rulesync generate --claudecode

# Generate only for Cursor
npx rulesync generate --cursor

# Generate only for Vs Code Copilot
npx rulesync generate --copilot

その他の AI ツール

rulesync は、GitHub Copilot、Cline、Aider など、19 以上の AI 開発ツールに対応しています。対応ツールの全一覧については、rulesync リポジトリをご確認ください。

指示ファイルには、次の内容が含まれています。

• MCP 開発のパターンと規約
• TypeScript の実装ガイドライン
• ビルダーとヘルパーを使った包括的なテスト標準
• プロジェクト固有の背景情報とアーキテクチャ
• Umbraco Management API との API 統合パターン