Elmapicms Mcp Server

ElmapiCMS MCP サーバー

Cursor や Claude Code などの AI エージェントを、お使いの ElmapiCMS インスタンスに接続する MCP（Model Context Protocol）サーバーです。自然言語を使って、コレクション、フィールド、コンテンツエントリー、アセット、ウェブフックをプログラムで管理できます。

設定

変数	説明
ELMAPI_BASE_URL	インスタンスの API ルート（例：https://your-domain.com/api）。エイリアスとして ELMAPI_API_URL も使用できます。
ELMAPI_API_KEY	Project settings → API Tokens で取得する、プロジェクトの Sanctum トークン
ELMAPI_PROJECT_ID	プロジェクトのホームページ、または Project settings → API Access で確認できるプロジェクト UUID

Cursor での使用方法

Cursor の MCP 設定（~/.cursor/mcp.json）に以下を追加します。

{
  "mcpServers": {
    "elmapicms": {
      "command": "npx",
      "args": ["-y", "@elmapicms/mcp-server"],
      "env": {
        "ELMAPI_BASE_URL": "https://your-domain.com/api",
        "ELMAPI_API_KEY": "your-project-api-token",
        "ELMAPI_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

Claude Code での使用方法

claude mcp add elmapicms \
  -e ELMAPI_BASE_URL=https://your-domain.com/api \
  -e ELMAPI_API_KEY=your-project-api-token \
  -e ELMAPI_PROJECT_ID=your-project-uuid \
  -- npx -y @elmapicms/mcp-server

ローカル開発（Laravel Herd / .test ドメイン）

インスタンスで自己署名証明書（例：Laravel Herd）を使用している場合は、次の設定が必要になることがあります。

"env": {
  "ELMAPI_BASE_URL": "https://myproject.test/api",
  "ELMAPI_API_KEY": "your-project-api-token",
  "ELMAPI_PROJECT_ID": "your-project-uuid",
  "NODE_TLS_REJECT_UNAUTHORIZED": "0"
}

本番環境の設定で TLS 検証を無効にするのではなく、ローカル CA の信頼設定を修正すること（例：node --use-system-ca）を推奨します。

使用可能なツール（40）

プロジェクト

• get_project — プロジェクト情報（default_locale、locales など）を取得します
• add_project_locale — プロジェクトにロケールコードを追加します（admin 権限が必要です）
• set_default_project_locale — デフォルトのロケールを設定します（admin 権限が必要です）

ロケールの削除機能は、意図的にここでは公開していません（ダッシュボードの Project settings → Localization、または REST／SDK API を使用してください）。

コレクション

• list_collections — すべてのコレクションを一覧表示します
• get_collection — フィールドスキーマ全体を含むコレクションを取得します
• create_collection — コレクションを作成します（フィールドの一括作成は任意です）
• update_collection — コレクションの名前とスラッグを更新します
• reorder_collections — コレクションの順序を変更します

フィールド

• create_field — コレクションにフィールドを追加します
• update_field — フィールドを更新します
• reorder_fields — コレクション内のフィールドの順序を変更します

コンテンツエントリー

• list_entries — 高度なフィルタリング（13種類の演算子を使うwhere、ORグループ、リレーションのフィルタリング）、並べ替え、ページネーション、件数、最初の項目を指定してエントリーを一覧表示
• get_entry — 1件のコンテンツエントリーを取得
• create_entry — コンテンツエントリーを作成
• update_entry — コンテンツエントリーを更新
• patch_entry — エントリーを部分更新（HTTP PATCH。送信したフィールドのみをマージ）
• publish_entry — 下書きを新しい不変バージョンとして公開（update）
• unpublish_entry — 公開中のポインターをクリア。バージョンは保持（update）
• discard_entry_draft — 未公開の下書き変更を破棄（update）
• delete_entry — コンテンツエントリーを論理削除（ゴミ箱に移動）
• bulk_create_entries — 複数のエントリーをアトミックに作成
• bulk_update_entries — UUIDを指定して複数のエントリーをアトミックに更新
• bulk_delete_entries — UUIDを指定して複数のエントリーをアトミックに削除
• link_entry_translation — 異なるロケールの2つのエントリーを同じ翻訳グループにリンク（POST …/link-translation。updateが必要）
• list_entry_versions — エントリーのバージョン履歴を一覧表示
• get_entry_version — 番号を指定して1つのバージョンを取得（スナップショットのペイロードを含む）
• revert_entry_version — 過去のスナップショットから下書きを復元して公開（update）
• update_entry_version_label — バージョンのラベル／説明を編集。スナップショットは変更されません（update）

コンテンツ API の形式： 各エントリーには、uuid、locale、published_at、および**fields（カスタムフィールド値）があります。フィールド名はケバブケースです。リッチテキストの書き込み形式はeditor.modeに従います。HTML文字列、またはlexicalの場合は{ html, json }です。modeがmarkdownの場合はMarkdown文字列です。MCPのcreate_field**／create_collection（およびリッチテキストのupdate_field）では、省略されたeditor.modeはデフォルトでmarkdownになります。Lexicalを使う場合はmode: 'lexical'を渡してください。lexicalフィールドにMarkdownを書き込まないでください。読み取り形式はeditor.outputFormatに従います。リレーションフィールドは読み取り時にネストされたエントリーオブジェクト（1対多の場合は配列）を返します。書き込み時には、関連するエントリーのUUIDまたは数値のidのみを送信してください（以前のget_entryで取得したネストされたオブジェクト全体は送信しないでください）。get_entryは、translation_locale、exclude、timestamps、stateのクエリパラメーターに対応しています。

保存 ≠ 公開： create_entry／update_entry／patch_entryで保存されるのは下書きのみです。state=publishedを指定した一覧取得／取得では、publish_entryを呼び出すまで最後のスナップショットが返されます。

アセット URL： APIはurl、thumbnail_url、original_urlを安定したリンクとして返します（任意で?variant=thumbnailまたは?variant=originalを指定できます）。

アセット

• list_assets — アセットをページネーション付きで一覧表示
• get_asset — UUIDまたはファイル名でアセットを取得
• upload_asset — ファイルをアセットとしてアップロード
• bulk_upload_assets — 複数のファイルをアトミックにアップロード
• bulk_update_asset_metadata — 複数のアセットのメタデータをアトミックに更新
• delete_asset — アセットを削除

Webhook

• list_webhooks — プロジェクトのすべてのWebhookを一覧表示
• get_webhook — UUIDでWebhookを取得
• create_webhook — コンテンツイベントと認証イベント用のWebhookを作成（name、url、events、sources。description、secret、payload、status、collection_idsは任意）
• update_webhook — UUIDでWebhookを更新（フィールドは作成時と同じ）
• delete_webhook — UUIDでWebhookを削除
• list_webhook_logs — Webhookの配信ログを一覧表示（uuid。paginate、pageは任意）

リソース

サーバーは、AIエージェントがコンテキストとして読み取れる3つのリファレンスリソースを公開します。

• フィールドタイプのリファレンス（elmapicms://field-types）— 全16種類のフィールドタイプ、そのオプション、バリデーション、一般的なパターンに関する完全なリファレンスです。
• コレクションガイド（elmapicms://collections-guide）— コレクション、シングルトン、予約済みスラッグ、ベストプラクティスに関するガイドです。
• クエリリファレンス（elmapicms://query-reference）— コンテンツクエリの詳細ドキュメントです。13種類の演算子を使うwhereフィルター、ORグループ、リレーションのフィルタリング、並べ替え、ページネーション、例を説明しています。

API トークンの権限

使用するツールに必要な権限が、プロジェクトの API トークンに設定されている必要があります。

権限	ツール
read	コレクション、エントリー、アセット、Webhook の一覧表示・取得、Webhook ログ
create	エントリーの作成、アセットのアップロード、Webhook の作成
update	エントリーの更新、公開／非公開／下書きの破棄、link_entry_translation、バージョン、アセットのメタデータの更新、Webhook の更新
delete	エントリーの削除、アセットの削除、Webhook の削除
admin	コレクションとフィールドの作成／更新／並べ替え、プロジェクトのロケールの追加／デフォルト設定（MCP ではロケールの削除はできません）

ElmapiCMS ダッシュボードの Project settings → API Tokens でトークンを作成してください。このサーバーを設定する際は、プロジェクトのホームページまたは Project settings → API Access から Project ID をコピーしてください。

複数のプロジェクトを使用する

各 MCP エントリーは、単一の ElmapiCMS プロジェクトに接続します。複数のプロジェクトで作業するには、MCP 設定に異なる環境変数値を指定したエントリーを追加してください。

ライセンス

MIT