What is Datocms Mcp Tools

datocms-mcp-tools is a Model Context Protocol (MCP) server that facilitates interaction between Claude AI models and DatoCMS, providing a standardized interface for managing various aspects of DatoCMS content and configuration.

Use cases

Use cases include automating content updates, managing user roles and permissions, scheduling content publications, and integrating DatoCMS with AI models for enhanced content delivery.

How to use

To use datocms-mcp-tools, set up the server and configure it to connect with your DatoCMS project. Utilize the provided API endpoints to manage content, collaborators, environments, and other resources as needed.

Key features

Key features include content management (CRUD operations), publication management (publish/unpublish/schedule), collaborator management (user and role management), API token management, environment management, schema management, upload management, and project configuration.

Where to use

datocms-mcp-tools can be used in web development, content management systems, and any application that requires dynamic content management and collaboration through DatoCMS.

DatoCMS MCP Server

📋 Table of Contents

• Overview
• Quick Start
• Features
• Architecture
• Installation
• Configuration
• Usage
• API Reference
• Field Creation Guide
• Known Limitations
• Development
• Debug Mode
• Troubleshooting
• Contributing
• License

Overview

The DatoCMS MCP Server enables Claude AI to interact with DatoCMS through the Model Context Protocol (MCP), providing a standardized interface for content management operations. This allows you to use natural language to manage your DatoCMS content, schema, media, and more.

What is MCP?

Model Context Protocol (MCP) is an open protocol that enables secure, controlled interactions between AI models and external systems. It provides:

• 🔒 Secure API Integration - Your API tokens stay local
• 🎯 Structured Tool Access - Well-defined operations with validation
• 📊 Transparent Operations - See exactly what actions are performed
• 🔄 Two-Step Confirmation - Preview parameters before execution

🚀 Quick Start

# Clone and install
git clone https://github.com/marcelofinamorvieira/datocms-mcp-server.git
cd datocms-mcp-server
npm install
npm run build

# Start the server
npm run start

# Configure Claude Desktop (see Configuration section)

✨ Features

Content Management

• 📝 Records - Create, read, update, delete, publish/unpublish records
• 🏷️ Versioning - Access and restore previous versions
• 🌍 Localization - Full support for multi-locale content
• 🔗 References - Find where records are referenced

Schema Management

• 🏗️ Models - Create and manage content models
• 🎨 Fields - Add fields with proper validation and appearance
• 📦 Fieldsets - Group related fields together
• 🔧 Field Helpers - Get field type information and examples

Media Management

• 📤 Uploads - Upload and manage media assets
• 📁 Collections - Organize uploads into collections
• 🏷️ Tagging - Tag and categorize uploads
• 🔍 Smart Tags - Auto-generated tags for images

Project Configuration

• ⚙️ Settings - Manage project settings
• 🌐 Environments - Create, fork, and promote environments
• 🔧 Maintenance Mode - Toggle maintenance mode
• 📊 Project Info - Access project metadata

Team Management

• 👥 Collaborators - Invite and manage team members
• 🔐 Roles - Define custom roles and permissions
• 🔑 API Tokens - Create and manage API access tokens
• 📧 Invitations - Send and manage invitations

Automation

• 🔗 Webhooks - Configure webhook endpoints
• 🏗️ Build Triggers - Set up deployment triggers
• 📡 Webhook Calls - Monitor and resend webhook calls
• 🚀 Deploy Events - Track deployment history

UI Customization

• 📋 Menu Items - Customize navigation menu
• 🔌 Plugins - Install and configure plugins
• 🎯 Filters - Create custom content filters
• 🎨 Schema Menu - Organize schema navigation

🏗️ Architecture

System Overview

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Claude AI     │────▶│   MCP Server     │────▶│  DatoCMS API    │
│                 │◀────│                  │◀────│                 │
│  Natural Lang   │     │  ┌────────────┐  │     │  Content Mgmt   │
│   Requests      │     │  │Router Tools│  │     │    Platform     │
└─────────────────┘     │  └─────┬──────┘  │     └─────────────────┘
                        │        │         │
                        │  ┌─────▼──────┐  │
                        │  │  Handlers  │  │
                        │  └─────┬──────┘  │
                        │        │         │
                        │  ┌─────▼──────┐  │
                        │  │Zod Schemas │  │
                        │  └────────────┘  │
                        └──────────────────┘

Core Components

Component	Purpose	Location
Router Tools	Route operations to handlers	src/tools/*/RouterTool.ts
Handlers	Execute specific operations	src/tools/*/handlers/
Schemas	Validate input parameters	src/tools/*/schemas.ts
Utilities	Shared functionality	src/utils/
Debug System	Execution tracking & monitoring	src/utils/debug*.ts
Type System	Official DatoCMS types	@datocms/cma-client-node

Router Tools Reference

Router	Domain	Key Operations
RecordsRouterTool	Content records	CRUD, publish, versions, references
SchemaRouterTool	Schema management	Models, fields, fieldsets
UploadsRouterTool	Media assets	Upload, organize, tag
EnvironmentRouterTool	Environments	Create, fork, promote
ProjectRouterTool	Project config	Settings, info
CollaboratorsRolesAndAPITokensRouterTool	Team	Users, roles, tokens
WebhookAndBuildTriggerCallsAndDeploysRouterTool	Automation	Webhooks, builds
UIRouterTool	UI customization	Menus, plugins, filters

📦 Installation

Prerequisites

• Node.js v16 or higher
• npm v7 or higher
• TypeScript v5.0 or higher (installed automatically)
• DatoCMS account with API access
• Claude Desktop v1.5.12+ or Claude AI with MCP support

Step-by-Step Installation

1. Clone the repository

   git clone https://github.com/marcelofinamorvieira/datocms-mcp-server.git
   cd datocms-mcp-server
   

2. Install dependencies

   npm install
   

3. Build the project

   npm run build
   

4. Verify installation

   npm run validate  # Validates directory structure
   

⚙️ Configuration

Claude Desktop Configuration

1. Open Claude Desktop settings

   • Mac: Claude → Settings → Developer
   • Windows: File → Settings → Developer

2. Add the MCP server

   {
     "mcpServers": {
       "datocms": {
         "command": "/absolute/path/to/datocms-mcp-server/start-server.sh",
         "autoStart": true,
         "alwaysAllow": true
       }
     }
   }
   

3. Restart Claude Desktop

Environment Variables (Optional)

Create a .env file in the project root for global configuration:

# .env file (all settings are optional)
DEBUG=false                # Enable global debug mode (development only!)
TRACK_PERFORMANCE=false    # Enable performance tracking
LOG_LEVEL=info            # Log level (error, warn, info, debug)
NODE_ENV=production       # Environment (development, production)

📝 Note: Environment variables are optional. Users can enable debug mode per-request by adding debug: true to any tool parameters, which is the recommended approach for production environments.

⚠️ Warning: Never enable DEBUG=true globally in production as it affects all users and may expose sensitive information.

💬 Usage

Two-Step Execution Pattern

The MCP server uses a two-step pattern for safety:

1. Parameter Discovery - Check what parameters are needed
2. Action Execution - Execute with the correct parameters

Basic Examples

Query Records

User: "Show me how to query blog posts"
Claude: I'll show you the parameters needed for querying records...

User: "Query all blog posts using this token: [YOUR_TOKEN]"
Claude: I'll query the blog posts for you...

Create a Model

User: "Create a new model called 'Product' with title and price fields"
Claude: I'll help you create a Product model. First, let me check the required parameters...

Upload Media

User: "Upload this image URL as a media asset: https://example.com/image.jpg"
Claude: I'll upload that image to your DatoCMS media library...

Advanced Examples

Complex Field Creation

User: "Add a structured text field to the blog model that allows headings, lists, and links to other articles"
Claude: I'll add a structured text field with those specifications...

Environment Management

User: "Fork the main environment to create a staging environment"
Claude: I'll fork your main environment to create a staging environment...

Bulk Operations

User: "Publish all draft blog posts from the last week"
Claude: I'll find and publish all draft blog posts from the last week...

Debug Mode Usage

User: "List all item types with debug information"
Claude: I'll list the item types with debug output enabled...

// Claude will use:
datocms_list_item_types({
  api_token: "your-token",
  debug: true  // ← Debug enabled for this request
})

📚 API Reference

Common Parameters

Parameter	Type	Description	Required
api_token	string	DatoCMS API token	✅
environment	string	Target environment (default: “main”)	❌
locale	string	Content locale	❌
debug	boolean	Enable debug output for this request	❌

Response Format

All responses follow this structure:

{
  success: boolean;
  data?: any;
  error?: string;
  message?: string;
  meta?: {
    total_count?: number;
    page_count?: number;
    debug?: {              // Only included when DEBUG=true
      context: {
        operation: string;
        handler: string;
        domain: string;
        timestamp: number;
        parameters: any;   // Sanitized
        performance: {
          duration: number;
          stages: Record<string, number>;
        };
        trace: string[];
      };
      response?: {
        dataSize: number;
        dataType: string;
      };
      error?: {
        type: string;
        message: string;
        stack?: string;    // Only in debug mode
      };
    };
  };
}

📝 Field Creation Guide

Critical Requirements

1. Appearances must include addons

   appearance: {
     editor: "single_line",
     addons: []  // Required even if empty
   }
   

2. Field-Specific Rules

   • Location: Use "editor": "map" (not "lat_lon_editor")
   • String with radio/select: Enum validator must match options
   • Rich text: Requires rich_text_blocks validator
   • Structured text: Needs both structured_text_blocks and structured_text_links
   • Slug: Requires slug_title_field validator

3. Unsupported Validators

   • The required validator doesn’t work on: gallery, links, rich_text

For detailed examples, see Field Creation Guide.

⚠️ Known Limitations

Feature	Limitation	Workaround
Record Creation	May fail with complex fields (structured text, blocks)	Create with simple fields first, then update
Record Updates	Complex field updates may fail	Update fields individually
Role Management	Complex parameter sets fail	Use minimal parameters, update incrementally
Field Creation	Some validator combinations unsupported	Check field creation guide

🛠️ Development

Development Workflow

# Start TypeScript compiler in watch mode
npm run dev

# In another terminal, start the server
npm run start

# Type checking commands
npm run type-check              # Basic type checking
npm run type-check:handlers     # Check all handler types  
npm run type-check:strict       # Strict mode with all checks

# Validate structure
npm run validate

# Test debug functionality
npm run test:debug

Adding New Features

1. Create domain structure

   src/tools/YourDomain/
   ├── Create/
   │   ├── handlers/
   │   └── index.ts
   ├── Read/
   ├── Update/
   ├── Delete/
   ├── YourDomainRouterTool.ts
   ├── schemas.ts
   └── index.ts
   

2. Define schemas using Zod with descriptive documentation

3. Implement handlers using enhanced factory functions

4. Create router tool for action dispatch

5. Register in src/index.ts

Enhanced Handler Factory Pattern

The project uses enhanced factory functions that provide automatic error handling, validation, and debug tracking:

import { createRetrieveHandler } from "../../../../utils/enhancedHandlerFactory.js";

export const getResourceHandler = createRetrieveHandler({
  domain: "resources",
  schemaName: "get",
  schema: domainSchemas.get,
  entityName: "Resource",
  idParam: "resourceId",
  clientAction: async (client, args) => {
    return await client.resources.find(args.resourceId);
  }
});

Available factories:

• createListHandler - For listing resources with pagination
• createRetrieveHandler - For getting single resources by ID
• createWriteHandler - For create, update, and delete operations
• createActionHandler - For custom operations

See Contributing Guide for detailed instructions.

🔧 Troubleshooting

Common Issues

Server won’t start

• Check Node.js version (must be v16+)
• Verify all dependencies installed: npm install
• Ensure build completed: npm run build

Claude can’t connect

• Verify absolute path in Claude settings
• Check server is running: ps aux | grep datocms-mcp
• Restart Claude Desktop after configuration

API errors

• Validate API token has necessary permissions
• Check environment name is correct
• Verify rate limits haven’t been exceeded

Field creation fails

• Review Field Creation Guide
• Ensure all appearances include addons: []
• Check validator compatibility

🔍 Debug System

The DatoCMS MCP Server includes a sophisticated debug system that provides comprehensive execution tracking and performance monitoring. Since console.log output isn’t visible in the MCP environment, all debug information is returned as part of the response structure.

🚀 Quick Start

The debug system supports two modes:

1. Per-Request Debug Mode (Recommended for Production)

Add the debug parameter to any request:

// Enable debug for a specific request
{
  api_token: "your-token",
  environment: "main",
  debug: true  // ← Enable debug for this request only
}

✅ Benefits of per-request debug:

• Safe for production use
• No performance impact on other requests
• User-controlled debugging
• Isolated debug output

2. Global Debug Mode (Development Only)

Enable debug mode in .env:

DEBUG=true                 # Enable comprehensive debug tracking
TRACK_PERFORMANCE=true     # Enable detailed performance metrics
LOG_LEVEL=debug           # Set verbose logging

⚠️ Warning: Global debug mode should NEVER be used in production or with public MCP servers as it affects all users.

📊 Debug Response Structure

When debug mode is enabled, every response includes comprehensive debug information:

{
  success: boolean,
  data: any,
  meta: {
    debug: {
      context: {
        operation: string,        // CRUD operation type (create, read, update, delete, custom)
        handler: string,          // Specific handler name (e.g., "createRecordHandler")
        domain: string,           // Domain/module (e.g., "records", "schema", "uploads")
        timestamp: number,        // Operation start timestamp
        parameters: object,       // Request parameters (API tokens automatically redacted)
        performance: {
          startTime: number,      // Start timestamp
          endTime: number,        // End timestamp  
          duration: number,       // Total execution time in milliseconds
          apiCallDuration: number,// Time spent on DatoCMS API calls
          stages: {
            validation: number,   // Schema validation time
            handler: number       // Handler execution time
          }
        },
        trace: string[]          // Step-by-step execution log with timestamps
      },
      response: {
        dataSize: number,        // Response payload size in bytes
        dataType: string         // Type of data returned
      },
      api: {                     // DatoCMS API call information
        endpoint: string,        // API endpoint called
        method: string,          // HTTP method used
        duration: number         // API call duration
      },
      error?: {                  // Only present on errors
        type: string,            // Error type/class
        message: string,         // Error message
        stack: string,           // Full stack trace (debug mode only)
        details: object          // Additional error details from API
      }
    }
  }
}

🎯 Debug Features

1. Per-Request Debug Control

The debug parameter provides:

• User isolation: Each user controls their own debug state
• No contamination: Debug state doesn’t affect other users
• Production safe: Can be used selectively without global impact
• Fine-grained control: Debug specific operations only

Example usage:

// Debug a problematic operation
{
  api_token: "your-token",
  itemTypeId: "blog_post",
  debug: true  // Only this request gets debug info
}

// Normal operation (no debug overhead)
{
  api_token: "your-token",
  itemTypeId: "author"
  // No debug parameter = no debug output
}

2. Automatic Execution Tracking

Every handler automatically tracks:

• Start/end timestamps
• Operation type and context
• Step-by-step execution traces
• Performance breakdowns by stage

3. Performance Monitoring

4. Security & Sanitization

• API tokens automatically redacted: "f9a6b2c8...a7b63db"
• Sensitive data filtered: Passwords, secrets, and keys
• Safe for logging: No sensitive information exposed

5. Detailed Execution Traces

{
  "trace": [
    "[+0ms] Starting createRecordHandler",
    "[+15ms] Validating input with create schema",
    "[+15ms] Validation completed in 15ms",
    "[+16ms] Initializing DatoCMS client",
    "[+18ms] Creating Record with itemType: blog_post",
    "[+195ms] Record created successfully: rec_abc123",
    "[+245ms] Handler completed in 230ms"
  ]
}

6. Error Context Enrichment

When errors occur, debug mode provides:

• Full error stack traces
• DatoCMS API error details
• Context about what operation was being performed
• Parameter values that caused the error (sanitized)

🛠️ Debug Configuration

Environment Variables

# .env configuration options
DEBUG=true|false                    # Master debug toggle
TRACK_PERFORMANCE=true|false        # Performance monitoring only
LOG_LEVEL=error|warn|info|debug     # Logging verbosity
NODE_ENV=development|production     # Environment mode

Debug Modes

Mode	Purpose	Use Case	Scope
debug: true (parameter)	Per-request debug	Debug specific operations	Single request
DEBUG=false	Production mode	No debug overhead, minimal logging	Global
TRACK_PERFORMANCE=true	Performance only	Monitor timing without full debug	Global
DEBUG=true	Full debug	Development, troubleshooting	Global

🔧 For Developers

Enhanced Factory Integration

All handlers using the enhanced factory pattern automatically get debug support:

import { createCreateHandler } from "../../../../utils/enhancedHandlerFactory.js";

// This handler automatically gets debug tracking
export const myHandler = createCreateHandler({
  domain: 'myDomain',
  schemaName: 'create', 
  schema: mySchema,
  entityName: 'MyEntity',
  clientAction: async (client, args) => {
    // Your business logic here
    // Debug tracking is automatic!
    return await client.myEntities.create(args);
  }
});

Manual Debug Integration (Advanced)

For custom handlers not using factories:

import { createDebugContext, addTrace, trackApiCall } from "./debugUtils.js";

export const customHandler = async (args) => {
  const context = createDebugContext({
    operation: 'custom',
    handler: 'customHandler',
    domain: 'myDomain',
    parameters: args
  });
  
  addTrace(context, 'Starting custom operation');
  
  const timer = createTimer();
  const result = await someApiCall();
  
  trackApiCall(context, {
    endpoint: '/custom',
    method: 'GET',
    duration: timer.stop()
  });
  
  return createStandardResponse(result, {
    debug: createDebugData(context)
  });
};

📈 Performance Analysis

Use debug data to analyze performance:

// Example debug output for performance analysis
{
  "performance": {
    "duration": 1250,           // Total time: 1.25 seconds
    "stages": {
      "validation": 25,          // Schema validation: 25ms
      "handler": 1225            // Handler logic: 1.225 seconds
    },
    "apiCallDuration": 1100     // API calls took 1.1 seconds
  }
}

Performance insights:

• High validation time: Complex schema or large payloads
• High handler time: Business logic optimization needed
• High API duration: Network latency or complex DatoCMS operations

🚨 Security Considerations

1. Production Recommendations

   # Production .env should have:
   DEBUG=false              # Disable global debug
   TRACK_PERFORMANCE=false  # Disable global performance tracking
   LOG_LEVEL=error         # Minimal logging
   

   Note: Per-request debug (debug: true parameter) is safe for production use as it only affects individual requests.

2. Automatic sanitization patterns:

   • API tokens: f9a6b2c8...a7b63db
   • Passwords: [REDACTED]
   • Keys ending in _key, _secret: [REDACTED]
   • URLs with tokens: Query parameters sanitized

3. Performance overhead:

   • Debug mode adds ~5-10ms per request
   • Memory usage increases for trace storage
   • Network payload size increases
   • Per-request debug has zero overhead when not used

🧪 Testing Debug Features

# Run the debug test script
npm run test:debug

# This will:
# 1. Enable debug mode
# 2. Execute a handler with invalid token
# 3. Show debug data in response
# 4. Demonstrate error tracking
# 5. Display performance metrics

🎛️ Debug Utilities Reference

Function	Purpose	Usage
createDebugContext()	Initialize debug tracking	Start of handler
addTrace()	Add execution step	Throughout handler
trackApiCall()	Record API call metrics	After API calls
createTimer()	Performance measurement	Time operations
sanitizeSensitiveData()	Remove sensitive info	Before logging
createDebugData()	Format debug response	End of handler
formatBytes()	Human readable sizes	Response formatting

💡 Debug Best Practices

1. Use enhanced factories for automatic debug support
2. Add meaningful traces for complex operations
3. Track API calls for performance analysis
4. Never commit with DEBUG=true
5. Monitor performance impact in development
6. Use debug data to optimize slow operations
7. Include context in error scenarios

🔍 Troubleshooting Debug Issues

Issue	Cause	Solution
No debug data in response	DEBUG=false	Set DEBUG=true in .env
Missing performance metrics	TRACK_PERFORMANCE=false	Enable performance tracking
Sensitive data visible	Missing sanitization pattern	Add pattern to debugUtils.ts
High debug overhead	Complex trace logging	Reduce trace granularity

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for:

• Code style guidelines
• Development setup
• Testing requirements
• Pull request process

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• DatoCMS Documentation
• MCP Protocol Specification
• Issue Tracker
• DatoCMS Community