Microcms MCP Server

🚀 microCMS MCP Server

microCMS MCP Server 是一个用于集成 microCMS API 的模型上下文协议（MCP）服务器。该服务器使像 Claude 这样的 AI 助手能够与 microCMS 内容管理系统进行交互。

microCMS

🚀 快速开始

要使用 microCMS MCP Server，你需要满足以下要求并完成相应的安装和配置步骤。

✨ 主要特性

• 内容管理：对 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"
  }
}

高级用法

完整示例

{
  "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"]
    }
  }
}

🔧 技术细节

字段类型规范

在创建或更新内容时，不同的字段类型需要特定的格式：

文本字段

"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"]

媒体管理

媒体检索 (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 参数。内容工具使用 Content API，而媒体工具使用 Management API。

错误处理

服务器为以下情况提供详细的错误消息：

• 缺少必需的环境变量。
• 无效的 API 请求。
• microCMS API 错误。
• 工具参数格式错误。

📄 许可证

本项目采用 MIT 许可证。