What is Microcms Mcp Server

microcms-mcp-server is a Model Context Protocol (MCP) server designed for integrating with the microCMS API. It enables AI assistants to interact seamlessly with the microCMS content management system.

Use cases

Use cases include building dynamic websites that pull content from microCMS, developing AI assistants that require real-time content updates, and creating applications that need efficient content management and retrieval functionalities.

How to use

To use microcms-mcp-server, you can either run it directly using npx without installation or install it globally via npm. You need to provide your microCMS service ID and API key either through environment variables or command line arguments.

Key features

Key features include full CRUD operations for microCMS list-type APIs, eight core tools for content management, and full API support for all microCMS query parameters, including drafts, filters, pagination, and depth expansion.

Where to use

microcms-mcp-server can be used in various fields that require content management, such as web development, mobile applications, and AI-driven applications that need to manage and retrieve content dynamically.

microCMS MCP Server

A Model Context Protocol (MCP) server for microCMS API integration. This server enables AI assistants like Claude to interact with microCMS content management system.

microCMS

Features

• Content Management: Full CRUD operations for microCMS list-type APIs
• Eight Core Tools:
  • microcms_get_list - Retrieve content lists with filtering and pagination
  • microcms_get_content - Get individual content items
  • microcms_create_content - Create new content
  • microcms_update_content - Update content (PUT)
  • microcms_patch_content - Partially update content (PATCH)
  • microcms_delete_content - Delete content
  • microcms_get_media - Retrieve media files (Management API)
  • microcms_upload_media - Upload media files (Management API)
• Full API Support: Supports all microCMS query parameters including drafts, filters, pagination, and depth expansion

Requirements

• Node.js 18.0.0 or higher
• microCMS account and API key

Installation

Method 1: Using npx (Recommended)

No installation required! Use directly with npx:

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

Method 2: Global Installation

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

Method 3: Development Setup

1. Clone this repository

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Configuration

You can configure microCMS credentials in two ways:

Method 1: Environment Variables

1. Copy the environment template:

   cp .env.example .env
   

2. Configure your microCMS credentials in .env:

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

Method 2: Command Line Arguments

Pass credentials directly as command line arguments:

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

Note: Command line arguments take precedence over environment variables.

Usage

Running the Server

Using environment variables:

npm start

Using command line arguments:

npm run start:args
# or directly:
node dist/index.js --service-id your-service-id --api-key your-api-key

Using with Claude Desktop

Add the following to your Claude Desktop MCP configuration file:

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

Option 1: Using npx (Recommended)

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

Option 2: Using global installation

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

Option 3: Using local development setup

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

Replace:

• your-service-id with your microCMS service ID
• your-api-key with your microCMS API key
• /path/to/microcms-mcp-server/ with the actual path (Option 3 only)

Restart Claude Desktop after updating the configuration.

Development Mode

npm run dev

Available Scripts

• npm run build - Build TypeScript to JavaScript
• npm start - Run the compiled server
• npm run dev - Development mode with auto-reload
• npm run lint - Run ESLint
• npm run format - Format code with Prettier

Tool Examples

Get Content List

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

Get Individual Content

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

Create New Content

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

Update Content with Image

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

Get Media Files

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

Upload Media File (Base64)

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

Upload Media File (External URL)

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

Field Type Specifications

When creating or updating content, different field types require specific formats:

Text Fields

Rich Editor Fields

Image Fields

Must use URLs from the same microCMS service:

Multiple Image Fields

Date Fields

Use ISO 8601 format:

Select Fields

Content Reference Fields

Single reference:

Multiple references:

Complete Example

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

Media Management

Media Retrieval (microcms_get_media)

• API Type: Management API v2 (direct fetch)
• Permissions: Requires “media retrieval” permissions
• Features:
  • Pagination with tokens (15-second validity)
  • Filter by filename
  • Image-only filtering
  • Returns URLs, dimensions, and metadata

Media Upload (microcms_upload_media)

• API Type: Management API v1 (via JS SDK)
• Permissions: Requires “media upload” permissions
• Upload Methods:
  1. File Data Upload: Base64 encoded file data with filename and mimeType
  2. External URL Upload: Direct upload from external URL
• Limitations:
  • File size: 5MB maximum
  • One file per request
  • Available on Team, Business, Advanced, Enterprise plans
• Returns: microCMS asset URLs
  • Images: https://images.microcms-assets.io/...
  • Files: https://files.microcms-assets.io/...

API Reference

All tools support the full range of microCMS API parameters. Content tools use the Content API, while media tools use the Management API.

Error Handling

The server provides detailed error messages for:

• Missing required environment variables
• Invalid API requests
• microCMS API errors
• Malformed tool parameters

License

MIT