microCMS MCP Server

Instructions

Implementation Reference

• src/tools/upload-media.ts:31-71 (handler)

  Core implementation of the microcms_upload_media tool handler. Uploads media to microCMS using the management client, supporting base64-encoded file data (with size check) or external URL.

  export async function handleUploadMedia(params: MediaToolParameters) {
    const { fileData, fileName, mimeType, externalUrl } = params;
  
    try {
      // Method 1: Upload from external URL
      if (externalUrl) {
        const result = await microCMSManagementClient.uploadMedia({
          data: externalUrl,
        });
        return result;
      }
  
      // Method 2: Upload file data
      if (fileData && fileName && mimeType) {
        // Convert base64 to buffer
        const buffer = Buffer.from(fileData, 'base64');
  
        // Check file size (5MB limit)
        if (buffer.length > 5 * 1024 * 1024) {
          throw new Error('File size exceeds 5MB limit');
        }
  
        // Create Blob from buffer (for Node.js environment)
        const data = new Blob([buffer], { type: mimeType });
  
        const result = await microCMSManagementClient.uploadMedia({
          data,
          name: fileName,
        });
  
        return result;
      }
  
      throw new Error('Either externalUrl or (fileData + fileName + mimeType) must be provided');
    } catch (error) {
      if (error instanceof Error) {
        throw new Error(`Media upload failed: ${error.message}`);
      }
      throw new Error('Media upload failed: Unknown error');
    }
  }

• src/tools/upload-media.ts:5-29 (schema)

  Tool metadata including name, description, and input schema definition for the microcms_upload_media tool.

  export const uploadMediaTool: Tool = {
    name: 'microcms_upload_media',
    description: 'Upload media files to microCMS using JS SDK (Management API). Supports two methods: 1) Upload file data (base64) with filename and mimeType, 2) Upload from external URL. Returns microCMS asset URL. Requires media upload permissions. Available on Team, Business, Advanced, and Enterprise plans.',
    inputSchema: {
      type: 'object',
      properties: {
        fileData: {
          type: 'string',
          description: 'Base64 encoded file data (for direct file upload)',
        },
        fileName: {
          type: 'string',
          description: 'File name with extension (e.g., "image.jpg", "document.pdf") - required when using fileData',
        },
        mimeType: {
          type: 'string',
          description: 'MIME type of the file (e.g., "image/jpeg", "application/pdf") - required when using fileData',
        },
        externalUrl: {
          type: 'string',
          description: 'External URL of the file to upload (alternative to fileData)',
        },
      },
    },
  };

• src/server.ts:47-72 (registration)

  Registers the uploadMediaTool (microcms_upload_media) in the server's list of available tools for the ListToolsRequest handler.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        getListTool,
        getListMetaTool,
        getContentTool,
        getContentMetaTool,
        createContentPublishedTool,
        createContentDraftTool,
        createContentsBulkPublishedTool,
        createContentsBulkDraftTool,
        updateContentPublishedTool,
        updateContentDraftTool,
        patchContentTool,
        patchContentStatusTool,
        patchContentCreatedByTool,
        deleteContentTool,
        getMediaTool,
        uploadMediaTool,
        deleteMediaTool,
        getApiInfoTool,
        getApiListTool,
        getMemberTool,
      ],
    };
  });

• src/server.ts:127-129 (registration)

  Switch case in CallToolRequest handler that dispatches 'microcms_upload_media' calls to the handleUploadMedia function.

  case 'microcms_upload_media':
    result = await handleUploadMedia(params as unknown as MediaToolParameters);
    break;

• src/server.ts:21-21 (registration)

  Import of the uploadMediaTool and its handler from the upload-media module.

  import { uploadMediaTool, handleUploadMedia } from './tools/upload-media.js';