Claude Code 能流暢操作您的儲存庫，但對您的內容一無所知。它可以重構渲染部落格的元件，但當要求它發布該元件所顯示的文章時，卻無處可尋。Model Context Protocol (MCP) 彌補了這個缺口。它為 Claude Code 提供了一組可直接呼叫 CMS 的工具，讓讀取和寫入內容與撰寫程式碼發生在同一次對話中。

本指南將引導您將 Claude Code 連接到 Cosmic 儲存桶。使用託管端點只需約五分鐘，無需安裝任何軟體。

MCP 究竟能為 Claude Code 提供什麼

MCP 是一種開放式協定，用於將工具暴露給 AI 助理。Cosmic MCP 伺服器實作了這項協定，並在四個領域提供了 18 個工具：

  • 物件 (5 個工具)：列出、取得、建立、更新和刪除內容
  • 媒體 (4 個工具)：列出、取得、上傳和刪除檔案
  • 物件類型 (5 個工具)：列出、取得、建立、更新和刪除內容模型
  • AI 生成 (4 個工具)：在您的儲存桶中生成文字、圖像、影片和音訊

連接完成後，「發布 MCP 草稿並為其生成主圖」會轉換為對您的儲存桶的實際工具呼叫。無需瀏覽器分頁、無需複製貼上、無需手動匯出。

有兩種連接方式：

  • 託管 MCP（推薦）：將您的用戶端指向 https://mcp.cosmicjs.com/v1/buckets/{your-bucket-slug} 並使用您的儲存桶金鑰進行驗證。無需安裝任何東西。
  • 自託管 (stdio)：透過 npx 在本機執行 @cosmicjs/mcp npm 套件。適用於離線工作，或當您希望 MCP 處理程序在自己的開發環境中執行時。

開始之前

您需要三樣東西：

  1. 一個 Cosmic 儲存桶。免費方案每月 0 美元，包含 1 個儲存桶、2 位團隊成員和 1,000 個物件，足以跟隨本指南操作。免費開始。
  2. 您的儲存桶 slug、讀取金鑰和寫入金鑰。步驟 1 將說明如何找到它們。
  3. 已安裝 Claude Code。

託管路徑完全不需要本機執行環境。只有在選擇自託管 stdio 選項時才需要 Node，因為該選項會透過 npx 執行。

步驟 1：取得您的儲存桶憑證

  1. 登入 Cosmic 儀表板
  2. 導覽至您的儲存桶
  3. 前往 設定 -> API 存取
  4. 複製您的 儲存桶 slug、讀取金鑰 和 寫入金鑰

在貼上任何內容之前，建議先從讀取金鑰開始。Cosmic 會為每個儲存桶發出獨立的讀取和寫入金鑰，因此您可以讓 Claude Code 完全看到您的內容，同時在結構上使其無法更改內容。一旦您信任設定，再加入寫入金鑰。下面的唯讀與完整存取權限部分將詳細說明具體的差異。

步驟 2：使用託管 MCP 連接（推薦）

Claude Code 會從儲存庫根目錄的 .mcp.json 檔案中讀取專案範圍的 MCP 伺服器。建立方式如下：

{
  "mcpServers": {
    "cosmic": {
      "url": "https://mcp.cosmicjs.com/v1/buckets/your-bucket-slug",
      "headers": {
        "Authorization": "Bearer your-read-key:your-write-key"
      }
    }
  }
}

進入全螢幕模式 退出全螢幕模式

請將 your-bucket-slug、your-read-key 和 your-write-key 替換為步驟 1 中的值。此端點支援 streamable-HTTP MCP 傳輸。

授權標頭的工作原理

Cosmic 會將兩個金鑰打包成單一 bearer token，以冒號分隔。寫入金鑰位於冒號之後：

# 唯讀存取
Authorization: Bearer rk_abc123def456

# 完整存取（讀取 + 寫入）
Authorization: Bearer rk_abc123def456:wk_zyx987wvu654

進入全螢幕模式 退出全螢幕模式

若要唯讀存取，請省略冒號和寫入金鑰。如果您的用戶端無法傳送冒號分隔的 token，您可以使用 X-Cosmic-Write-Key 標頭來傳遞寫入金鑰。

提醒事項：.mcp.json 現在包含即時憑證，請在下次提交前將其加入 .gitignore。

相同的 mcpServers 區塊也適用於 Claude Desktop 和 Cursor。MCP 伺服器文件列出了每個用戶端的確切設定檔路徑，包括 macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json 和 Cursor 的 .cursor/mcp.json。

步驟 2，替代方案：透過 stdio 自託管

如果您希望自行執行伺服器，@cosmicjs/mcp 套件提供 stdio 二進位檔。將 Claude Code 指向 npx：

{
  "mcpServers": {
    "cosmic": {
      "command": "npx",
      "args": ["@cosmicjs/mcp"],
      "env": {
        "COSMIC_BUCKET_SLUG": "your-bucket-slug",
        "COSMIC_READ_KEY": "your-read-key",
        "COSMIC_WRITE_KEY": "your-write-key"
      }
    }
  }
}

進入全螢幕模式 退出全螢幕模式

stdio 二進位檔會從環境變數讀取憑證：

  • COSMIC_BUCKET_SLUG (必填)：您的 Cosmic 儲存桶 slug
  • COSMIC_READ_KEY (必填)：儲存桶讀取金鑰，用於讀取操作
  • COSMIC_WRITE_KEY (選填)：儲存桶寫入金鑰，用於寫入操作

若要建立唯讀伺服器，請完全省略 COSMIC_WRITE_KEY。您也可以使用 npm install -g @cosmicjs/mcp 全域安裝，而非每次都透過 npx 解析。

步驟 3：驗證連接

重新啟動 Claude Code 並執行：

/mcp

進入全螢幕模式 退出全螢幕模式

您應該會看到 cosmic 及其工具列出。然後透過詢問只有您的儲存桶知道的內容來確認它是否能真正連接到您的儲存桶：

列出我 Cosmic 儲存桶中的所有物件類型

進入全螢幕模式 退出全螢幕模式

Claude Code 應該呼叫 cosmic_types_list 並回傳您真實的內容模型。如果它回傳您的物件類型，則表示連接已啟動且驗證正確。

18 個工具及其觸發時機

物件

  • cosmic_objects_list：列出或搜尋物件，可依類型、狀態和地區進行篩選，並支援分頁
  • cosmic_objects_get：依 ID 或 slug 取得單一物件，可選 metafield、深度 (depth) 和地區參數
  • cosmic_objects_create：建立具有標題、slug、狀態和 metafield 的新物件（需要寫入金鑰）
  • cosmic_objects_update：更新現有物件的標題、slug、狀態或 metafield 值（需要寫入金鑰）
  • cosmic_objects_delete：依 ID 永久刪除物件（需要寫入金鑰）

媒體

  • cosmic_media_list：列出媒體檔案，可選擇依資料夾範圍
  • cosmic_media_get：取得單一檔案的中繼資料和 imgix URL
  • cosmic_media_upload：從 URL 或 base64 有效負載上傳至媒體庫（需要寫入金鑰）
  • cosmic_media_delete：刪除媒體檔案（需要寫入金鑰）

物件類型

  • cosmic_types_list：列出儲存桶中的每個物件類型
  • cosmic_types_get：取得單一物件類型的完整結構描述，包括 metafield、選項和輔助說明
  • cosmic_types_create：建立具有 metafield 結構描述的新物件類型（需要寫入金鑰）
  • cosmic_types_update：更新物件類型的結構描述或 metafield 定義（需要寫入金鑰）
  • cosmic_types_delete：刪除物件類型及其所有物件（需要寫入金鑰）

AI 生成

  • cosmic_ai_generate_text：生成文字，可選擇從儲存桶中的現有物件提取內容
  • cosmic_ai_generate_image：生成圖像並儲存在媒體庫中（需要寫入金鑰）
  • cosmic_ai_generate_video：使用 Google Veo 生成影片並儲存在媒體庫中（需要寫入金鑰）
  • cosmic_ai_generate_audio：透過 OpenAI TTS 生成旁白，提供 13 種語音，儲存在媒體庫中（需要寫入金鑰）

值得用於代理人工作的兩個工具是 cosmic_types_list 和 cosmic_types_get。代理人在撰寫前先讀取您的結構描述，能在第一次嘗試時產生有效的 metafield，而非猜測金鑰名稱而失敗。

唯讀與完整存取

這是在將代理人指向生產環境儲存桶之前必須正確設定的部分。

使用唯讀 token 時，每個寫入工具都會被封鎖並顯示明確的錯誤訊息，而讀取工具則正常運作。具體來說，被封鎖的工具包括所有 *_create、*_update 和 *_delete 工具，以及所有四個 AI 生成工具，因為這些工具都會將生成的資產寫入您的媒體庫。

因此，唯讀設定仍能讓 Claude Code 探索您的內容模型、讀取每個物件，並在撰寫應用程式程式碼時對您的內容進行推理。它只是無法變更任何內容。這是針對真實資料進行首次工作階段的良好預設值。

實際操作範例

伺服器連接完成後，以下皆為單一提示：

列出我 Cosmic 儲存桶中的所有部落格文章

進入全螢幕模式 退出全螢幕模式 

建立一篇標題為「MCP 入門指南」的新部落格文章，內容為
「這是 Model Context Protocol 的介紹..."

進入全螢幕模式 退出全螢幕模式 

更新 ID 為「abc123」的部落格文章，將其狀態更改為已發布

進入全螢幕模式 退出全螢幕模式 

顯示「blog-images」資料夾中的所有圖像

進入全螢幕模式 退出全螢幕模式 

建立名為「Products」的新物件類型，包含名稱、價格、
描述和圖像欄位

進入全螢幕模式 退出全螢幕模式 

使用「nova」語音生成「歡迎使用 Cosmic CMS」的音訊旁白
並上傳至我的媒體庫

進入全螢幕模式 退出全螢幕模式

開發人員往往低估結構描述管理案例。內容建模通常是儀表板任務。透過 MCP，它可以從您搭建將使用該內容的元件時所使用的相同提示中完成。

代理人範圍：當使用者尚未擁有 Cosmic 帳戶時

託管端點在 https://mcp.cosmicjs.com/v1/agent 提供第二個較小的範圍，用於代理人註冊流程。它允許 AI 代理代表尚未擁有帳戶的使用者，在不離開 MCP 傳輸的情況下，代表其建立全新的 Cosmic 專案和儲存桶。它提供三個工具：

  • cosmic_agent_signup (無需驗證)：建立與 human_email 綁定的未領取專案和儲存桶。回傳 agent_key、read_key、write_key 和 claim_url。Cosmic 會寄送 6 位數 OTP 給使用者。
  • cosmic_agent_verify (需要 agent_key)：提交 OTP，解除受限模式限制，並啟用 AI 生成。
  • cosmic_agent_status (需要 agent_key)：檢查領取狀態、剩餘限制，並取回儲存桶金鑰。

新的儲存桶會以受限模式啟動：無 AI 點數、物件上限為 50 個，媒體上限為 5 MB。未領取的專案將在 14 天後被硬刪除。

先前列出的儲存桶範圍工具無法在代理人端點上使用，而代理人工具也無法在儲存桶端點上使用。單次對話通常會同時使用兩者：代理人為使用者註冊，擷取回傳的儲存桶金鑰，然後切換到儲存桶範圍開始建立內容。

MCP 伺服器與 Agent Skills

Cosmic 提供兩種聽起來相似但功能不同的東西：

  • MCP 伺服器：用於直接內容管理。它會回答「列出我的部落格文章」。AI 會呼叫操作儲存桶的工具。
  • Agent Skills：用於程式碼生成指導。它會回答「使用 Cosmic 建立部落格」。AI 會使用 SDK 撰寫應用程式程式碼。

請同時使用兩者。Agent Skills 能幫助 Claude Code 撰寫如下程式碼：

import { createBucketClient } from '@cosmicjs/sdk';

const cosmic = createBucketClient({
  bucketSlug: 'your-bucket-slug',
  readKey: 'your-read-key',
});

const { objects: posts } = await cosmic.objects
  .find({ type: 'blog-posts' })
  .props(['title', 'slug', 'metadata'])
  .depth(1);

進入全螢幕模式 退出全螢幕模式

然後，MCP 伺服器能讓同一次工作階段管理該程式碼所呈現的內容。一個工具撰寫應用程式，另一個操作其背後的資料。

生產環境儲存桶的安全措施

值得採用的四個習慣：

  1. 先使用讀取金鑰。在首次工作階段中使用唯讀 token 連接。在了解代理人實際執行的操作後，再加入寫入金鑰。
  2. 在獨立的儲存桶中進行實驗。儲存桶配額會隨您的方案而增加：免費方案包含 1 個，Builder（每月 49 美元）包含 2 個，Team（每月 299 美元）包含 3 個，Business（每月 499 美元）包含 5 個。將破壞性實驗指向您不介意遺失的儲存桶。
  3. 將刪除工具視為需手動核准。cosmic_objects_delete、cosmic_media_delete，特別是 cosmic_types_delete 是永久性的，刪除物件類型會一併刪除其所有物件。切勿讓代理人推測性地呼叫這些工具。
  4. 注意席位數。方案包含一定數量的團隊成員（免費 2 人、Builder 3 人、Team 5 人、Business 10 人），額外使用者每月 29 美元/人，因此請決定誰需要儀表板存取權，而非預設新增所有人。

疑難排解

伺服器未出現在 /mcp 中。請確認 .mcp.json 在儲存庫根目錄中是有效的 JSON，然後重新啟動 Claude Code。某些 Claude Code 版本需要明確指定傳輸，如果託管設定仍無法連接，請嘗試在 url 旁加入 "type": "http"。

npx 找不到套件。套件名稱為 @cosmicjs/mcp，是帶有 @ 的範圍套件。請確認 Node 已安裝並位於您的 PATH 中。

寫入工具回傳錯誤，但讀取正常。您的 bearer token 缺少寫入金鑰。請檢查標頭是否為 Bearer READ_KEY:WRITE_KEY（有冒號且無空格），或透過 X-Cosmic-Write-Key 傳送寫入金鑰。

託管端點回傳 404。URL 中的儲存桶 slug 錯誤。請從 設定 -> API 存取 再次複製，因為 slug 並非總是與專案顯示名稱相同。

工具已連接但未回傳任何內容。請確認您指向的是您認為的儲存桶。請 Claude Code 執行 cosmic_types_list 並將結果與儀表板進行比較。

後續步驟

從託管端點和唯讀 token 開始。要求 Claude Code 列出您的物件類型，然後要求它總結儲存桶中的內容。完成後，加入寫入金鑰並讓它起草內容。完整的工具參考和各用戶端的設定檔路徑，請參閱 MCP 伺服器文件。

立即親自體驗。Cosmic 是一款 AI 驅動的無頭 CMS，具備 REST API、TypeScript SDK 和託管 MCP 伺服器。建立免費帳戶，約五分鐘即可連接 Claude Code。若要為團隊評估 Cosmic？與 Tony 預約通話。

原文發表於 Cosmic 部落格。