Microcms MCP Server

🚀 microCMS MCP Server

microCMS MCP Server 是一個用於集成 microCMS API 的模型上下文協議（MCP）服務器。該服務器使 Claude 等 AI 助手能夠與 microCMS 內容管理系統進行交互。

microCMS

✨ 主要特性

• 內容管理：支持對 microCMS 列表類型 API 進行完整的 CRUD 操作。
• 八大核心工具：
  • microcms_get_list - 可通過過濾和分頁檢索內容列表。
  • microcms_get_content - 獲取單個內容項。
  • microcms_create_content - 創建新內容。
  • microcms_update_content - 更新內容（PUT 請求）。
  • microcms_patch_content - 部分更新內容（PATCH 請求）。
  • microcms_delete_content - 刪除內容。
  • microcms_get_media - 檢索媒體文件（管理 API）。
  • microcms_upload_media - 上傳媒體文件（管理 API）。
• 全 API 支持：支持所有 microCMS 查詢參數，包括草稿、過濾器、分頁和深度擴展。

📦 安裝指南

方法一：使用 npx（推薦）

無需安裝！直接使用 npx 運行：

npx microcms-mcp-server --service-id your-service-id --api-key your-api-key

方法二：全局安裝

npm install -g microcms-mcp-server
microcms-mcp-server --service-id your-service-id --api-key your-api-key

方法三：開發環境設置

1. 克隆此倉庫。
2. 安裝依賴：

npm install

3. 構建項目：

npm run build

🔧 配置說明

你可以通過兩種方式配置 microCMS 憑證：

方法一：環境變量

1. 複製環境模板：

cp .env.example .env

2. 在 .env 文件中配置你的 microCMS 憑證：

MICROCMS_SERVICE_ID=your-service-id
MICROCMS_API_KEY=your-api-key

方法二：命令行參數

直接將憑證作為命令行參數傳遞：

node dist/index.js --service-id your-service-id --api-key your-api-key

注意：命令行參數優先於環境變量。

💻 使用示例

啟動服務器

使用環境變量：

npm start

使用命令行參數：

npm run start:args
# 或者直接運行
node dist/index.js --service-id your-service-id --api-key your-api-key

與 Claude Desktop 配合使用

將以下內容添加到你的 Claude Desktop MCP 配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

選項一：使用 npx（推薦）

{
  "mcpServers": {
    "microcms": {
      "command": "npx",
      "args": [
        "-y",
        "microcms-mcp-server",
        "--service-id", "your-service-id",
        "--api-key", "your-api-key"
      ]
    }
  }
}

選項二：使用全局安裝

{
  "mcpServers": {
    "microcms": {
      "command": "microcms-mcp-server",
      "args": [
        "--service-id", "your-service-id",
        "--api-key", "your-api-key"
      ]
    }
  }
}

選項三：使用本地開發環境

{
  "mcpServers": {
    "microcms": {
      "command": "node",
      "args": [
        "/path/to/microcms-mcp-server/dist/index.js",
        "--service-id", "your-service-id",
        "--api-key", "your-api-key"
      ]
    }
  }
}

替換以下內容：

• your-service-id 替換為你的 microCMS 服務 ID。
• your-api-key 替換為你的 microCMS API 密鑰。
• /path/to/microcms-mcp-server/ 替換為實際路徑（僅選項三需要）。

更新配置後重啟 Claude Desktop。

開發模式

npm run dev

可用腳本

• npm run build - 將 TypeScript 編譯為 JavaScript。
• npm start - 運行編譯後的服務器。
• npm run dev - 開發模式，支持自動重新加載。
• npm run lint - 運行 ESLint 進行代碼檢查。
• npm run format - 使用 Prettier 格式化代碼。

工具使用示例

基礎用法

獲取內容列表

{
  "name": "microcms_get_list",
  "arguments": {
    "endpoint": "blogs",
    "limit": 10,
    "orders": "-publishedAt"
  }
}

獲取單個內容

{
  "name": "microcms_get_content",
  "arguments": {
    "endpoint": "blogs",
    "contentId": "article-1"
  }
}

高級用法

創建新內容

{
  "name": "microcms_create_content",
  "arguments": {
    "endpoint": "blogs",
    "content": {
      "title": "My Blog Post",
      "body": "Content here...",
      "category": "tech",
      "thumbnail": "https://example.com/image.jpg"
    }
  }
}

更新帶圖片的內容

{
  "name": "microcms_update_content",
  "arguments": {
    "endpoint": "blogs",
    "contentId": "article-1",
    "content": {
      "title": "Updated Title",
      "image": "https://example.com/new-image.jpg"
    }
  }
}

獲取媒體文件

{
  "name": "microcms_get_media",
  "arguments": {
    "limit": 20,
    "imageOnly": true,
    "fileName": "sample"
  }
}

上傳媒體文件（Base64 編碼）

{
  "name": "microcms_upload_media",
  "arguments": {
    "fileData": "base64-encoded-file-data",
    "fileName": "image.jpg",
    "mimeType": "image/jpeg"
  }
}

上傳媒體文件（外部 URL）

{
  "name": "microcms_upload_media",
  "arguments": {
    "externalUrl": "https://example.com/image.jpg"
  }
}

📚 詳細文檔

字段類型規範

創建或更新內容時，不同的字段類型需要特定的格式：

文本字段

"title": "Article Title"

富編輯器字段

"body": "<h1>見出し</h1><p>このようにHTMLで入稿できます</p>"

圖片字段

必須使用來自同一 microCMS 服務的 URL：

"thumbnail": "https://images.microcms-assets.io/assets/xxxxxxxx/yyyyyyyy/sample.png"

多圖片字段

"gallery": [
  "https://images.microcms-assets.io/assets/xxxxxxxx/yyyyyyyy/sample1.png",
  "https://images.microcms-assets.io/assets/xxxxxxxx/yyyyyyyy/sample2.png"
]

日期字段

使用 ISO 8601 格式：

"publishedAt": "2020-04-23T14:32:38.163Z"

選擇字段

"categories": ["カテゴリ1", "カテゴリ2"]

內容引用字段

單引用：

"relatedArticle": "article-id-123"

多引用：

"relatedArticles": ["article-id-123", "article-id-456"]

完整示例

{
  "name": "microcms_create_content",
  "arguments": {
    "endpoint": "blogs",
    "content": {
      "title": "My Blog Post",
      "body": "<h2>Introduction</h2><p>This is a paragraph with <strong>bold text</strong>.</p>",
      "thumbnail": "https://images.microcms-assets.io/assets/xxx/yyy/image.png",
      "publishedAt": "2024-01-15T10:30:00.000Z",
      "categories": ["tech", "tutorial"],
      "relatedArticles": ["article-1", "article-2"]
    }
  }
}

媒體管理

媒體檢索 (microcms_get_media)

• API 類型：管理 API v2（直接獲取）。
• 權限要求：需要“媒體檢索”權限。
• 特性：
  • 支持使用令牌進行分頁（有效期 15 秒）。
  • 可按文件名過濾。
  • 支持僅過濾圖片。
  • 返回 URL、尺寸和元數據。

媒體上傳 (microcms_upload_media)

• API 類型：管理 API v1（通過 JS SDK）。
• 權限要求：需要“媒體上傳”權限。
• 上傳方法：
  1. 文件數據上傳：使用 Base64 編碼的文件數據，並指定文件名和 mimeType。
  2. 外部 URL 上傳：直接從外部 URL 上傳。
• 限制條件：
  • 文件大小最大為 5MB。
  • 每次請求只能上傳一個文件。
  • 僅團隊、商業、高級和企業計劃可用。
• 返回結果：microCMS 資產 URL。
  • 圖片：https://images.microcms-assets.io/...
  • 文件：https://files.microcms-assets.io/...

API 參考

所有工具都支持完整的 microCMS API 參數。內容工具使用 內容 API，而媒體工具使用 管理 API。

錯誤處理

服務器針對以下情況提供詳細的錯誤消息：

• 缺少必需的環境變量。
• 無效的 API 請求。
• microCMS API 錯誤。
• 工具參數格式錯誤。

📄 許可證

MIT