MCP server

The DatoCMS MCP server connects DatoCMS directly to AI assistants through the Model Context Protocol (MCP). It allows MCP-compatible tools, such as Claude Code, Cursor, VS Code, and Windsurf, to securely interact with your DatoCMS project using natural language commands.

The DatoCMS MCP server acts as a bridge between AI assistants and the DatoCMS Content Management API, allowing large language models (LLMs) to interact with your DatoCMS project in a structured, secure, and standardized way. Unlike traditional MCP servers that simply expose raw API endpoints, this server uses a layered tool design that guides LLMs through discovery, planning, and execution stages, significantly improving success rates and reliability.

What you can do

The DatoCMS MCP server allows AI assistants to:

• Explore the API: Discover available resources, actions, and methods with complete documentation

• Inspect your schema: Retrieve detailed information about your content models, fields, and relationships

• Execute API operations: Perform both read-only and destructive operations on your DatoCMS project

• Write and run scripts: Create TypeScript scripts that batch multiple operations together

• Work with or without access: Use documentation tools without an API token, or provide a token for full execution capabilities

Users report excellent success rates for operations like:

• Create new records with content across multiple fields

• Upload and attach images to records

• Add translations to existing records

• Link records together (establishing relationships)

• Update content across multiple records

• Modify your content schema

Most operations complete fast and accurately, with occasional minor refinements needed (which can be requested in follow-up prompts).

Requirements

• Node.js 18 or newer

• A DatoCMS API token (for execution capabilities) or no token (for documentation only)

• An MCP-compatible client: Claude Code (recommended), ChatGPT Codex, VS Code, Cursor, Windsurf, or other MCP clients

Recommended clients

⭐ Claude Code (Recommended)

Claude Code provides the best experience with the DatoCMS MCP server:

• Fast and responsive performance

• Reliable execution without lag or UI issues

• Excellent success rate for complex operations

• Works seamlessly with all MCP tools

Other supported clients:

• ChatGPT Codex: Works reliably, though may be slower than Claude Code

• VS Code / Cursor: Good performance, works reliably

• Claude Desktop: ⚠️ Not recommended - can experience significant lag and UI issues that may affect usability

Installation

The DatoCMS MCP server can be installed using standard MCP configuration. Choose the installation method for your client:

Claude Code

Use the Claude Code CLI to add the DatoCMS MCP server:

claude mcp add datocms npx @datocms/mcp@latest -e DATOCMS_API_TOKEN=your-project-api-token-here

Optionally, specify the DatoCMS environment:

claude mcp add datocms npx @datocms/mcp@latest \
  -e DATOCMS_API_TOKEN=your-project-api-token-here \
  -e DATOCMS_ENVIRONMENT=your-environment-name

ChatGPT Codex

Use the ChatGPT Codex CLI to add the DatoCMS MCP server:

codex mcp add --env DATOCMS_API_TOKEN=your-project-api-token-here datocms -- npx @datocms/mcp@latest

Cursor

Go to Cursor Settings → Tools & Integrations → New MCP Server, then paste:

1
{
2
  "mcpServers": {
3
    "datocms": {
4
      "command": "npx -y @datocms/mcp@latest",
5
      "env": {
6
        "DATOCMS_API_TOKEN": "your-api-token-here"
7
      },
8
      "args": []
9
    }
10
  }
11
}

VS Code

Follow the MCP installation guide or use the VS Code CLI:

code --add-mcp '{"name":"datocms","command":"npx","args":["-y", "@datocms/mcp@latest"], "env": {"DATOCMS_API_TOKEN": "your-api-token-here"}}'

Windsurf

Follow Windsurf MCP documentation. Add to ~/.codeium/windsurf/mcp_config.json:

1
{
2
  "mcpServers": {
3
    "datocms": {
4
      "command": "npx",
5
      "args": ["-y", "@datocms/mcp@latest"],
6
      "env": {
7
        "DATOCMS_API_TOKEN": "your-api-token-here"
8
      }
9
    }
10
  }
11
}

Claude Desktop

Edit your config file at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%/Claude/config.json

Or go to Settings → Developer → Edit Config in Claude Desktop.

Add the following configuration:

1
{
2
  "mcpServers": {
3
    "datocms": {
4
      "command": "npx",
5
      "args": ["-y", "@datocms/mcp@latest"],
6
      "env": {
7
        "DATOCMS_API_TOKEN": "your-api-token-here"
8
      }
9
    }
10
  }
11
}

Restart Claude Desktop after saving.

Configuration

The DatoCMS MCP server supports the following environment variables:

Required for execution

• DATOCMS_API_TOKEN: Your DatoCMS API token for a specific project. When provided, enables full access including schema introspection, API execution, and script execution. Without this token, only API documentation and exploration tools are available, along with the ability to create and validate scripts (but not execute them).

Optional

• DATOCMS_ENVIRONMENT: Specifies which DatoCMS environment the MCP server should interact with. If not set, the server automatically uses the project's primary environment.

• EXECUTION_TIMEOUT_SECONDS: Script execution timeout in seconds. Defaults to 60 seconds.

• MAX_OUTPUT_BYTES: Maximum output size in bytes for all executions. Defaults to 2048 bytes (2 KB).

Configuration examples

With API token (full project access):

1
{
2
  "mcpServers": {
3
    "datocms": {
4
      "command": "npx",
5
      "args": ["-y", "@datocms/mcp@latest"],
6
      "env": {
7
        "DATOCMS_API_TOKEN": "your-api-token-here"
8
      }
9
    }
10
  }
11
}

With API token and custom environment:

1
{
2
  "mcpServers": {
3
    "datocms": {
4
      "command": "npx",
5
      "args": ["-y", "@datocms/mcp@latest"],
6
      "env": {
7
        "DATOCMS_API_TOKEN": "your-api-token-here",
8
        "DATOCMS_ENVIRONMENT": "staging"
9
      }
10
    }
11
  }
12
}

Without API token (documentation only):

{
  "mcpServers": {
    "datocms": {
      "command": "npx",
      "args": ["-y", "@datocms/mcp@latest"]
    }
  }
}

With custom execution limits:

1
{
2
  "mcpServers": {
3
    "datocms": {
4
      "command": "npx",
5
      "args": ["-y", "@datocms/mcp@latest"],
6
      "env": {
7
        "DATOCMS_API_TOKEN": "your-api-token-here",
8
        "EXECUTION_TIMEOUT_SECONDS": "120",
9
        "MAX_OUTPUT_BYTES": "4096"
10
      }
11
    }
12
  }
13
}

How it works

Unlike traditional MCPs that expose every API endpoint, the DatoCMS MCP server takes a different approach designed to guide AI assistants through API interactions effectively.

Layered tools, not raw endpoints

DatoCMS has 40+ resources and 150+ API endpoints. Exposing all of them would overwhelm any LLM. Instead, we provide 10 carefully designed tools organized in three layers (discovery → planning → execution) that guide the AI through a natural workflow:

Discovery layer - Tools that help explore what's available (no API token required):

• resources: List all available API resources grouped by theme

• resource: Get details about a specific resource and its available actions

• resource_action: Show available methods for a specific action with usage examples

Planning layer - Tools that provide detailed documentation (no API token required for docs, token required for schema):

• resource_action_method: Get complete TypeScript definitions for a specific method, including argument types, return types, and all dependencies

• schema_info: Retrieve detailed information about your content models, fields, relationships, and nested blocks (requires API token)

Execution layer - Tools that perform operations (require API token):

• resource_action_readonly_method_execute: Execute read-only operations (list, find, queries)

• resource_action_destructive_method_execute: Execute write operations (create, update, destroy)

• Script tools (create_script, view_script, update_script, execute_script): Create, manage, and execute TypeScript scripts that batch multiple operations together

This layered structure reduces malformed API calls and helps AI assistants understand the full context before executing operations.

Documentation-aware

Each tool retrieves detailed method documentation and concrete examples from the official DatoCMS documentation. This is token-intensive, but it significantly improves success rates by giving the LLM the context it needs to make correct API calls.

Script-based execution

Instead of making one API call at a time, the DatoCMS MCP server enables AI assistants to write complete TypeScript programs that batch multiple operations to reduce round-trips and token overhead, provide full context for complex multi-step operations, support incremental editing when errors occur, and get validated before execution to catch errors early.

Performance & reliability

Real-world performance

When using Claude Code (our recommended client), users report:

• Fast execution: Most common operations complete quickly without noticeable delays

• High success rates: Operations like creating records, adding images, managing translations, and linking records work reliably

• Minimal iteration needed: Most tasks succeed on the first attempt, with occasional minor refinements needed through follow-up prompts

• No missteps: The layered approach effectively prevents malformed API calls

What to expect

Common operations (fast & reliable):

• Creating records with content across multiple fields

• Uploading and attaching images to records

• Adding translations to existing content

• Linking records together

• Copying content between models

• Listing and querying records

Complex operations (slower but functional):

• Very complex operations like generating complete landing pages may take 5-10 minutes

• Large batch operations involving many records

• Schema modifications across multiple models

Token consumption

The documentation-aware approach retrieves full method documentation and examples for each operation. This consumes more tokens than traditional MCPs but significantly improves success rates. For most practical tasks, the token cost is acceptable given the reliability and accuracy of results.

Success tips

Results improve with:

• Clear, specific prompts: "Create a blog post with title 'Hello' and attach the uploaded image" works better than "add a post"

• Iterative refinement: If something is missing (like an image), a simple follow-up request handles it quickly

• Using Claude Code: The recommended client provides the best experience with fast, reliable execution

Limitations to be aware of

• Output limits: Very large records or complex batch operations may hit timeout or output limits (configurable via environment variables)

• Default limits: Script execution times out after 60 seconds (configurable), output limited to 2KB (configurable)

• Client-specific issues: Claude Desktop may experience lag and UI issues - use Claude Code instead

When it works best

The DatoCMS MCP server excels at:

• Everyday content management tasks (creating, updating, translating records)

• Complex multi-step operations that require understanding your content model

• Tasks that would be tedious to do manually (bulk updates, content migration)

• Operations that benefit from type safety and validation

Security

The DatoCMS MCP server implements multiple security layers:

Script validation

All scripts undergo strict validation before execution:

1. Package whitelist: Scripts can only import from:

   • @datocms/* - DatoCMS official packages

   • datocms-* - DatoCMS-prefixed packages

   • ./schema - Local schema definitions

2. Enforced function signature: Scripts must export a default async function with exactly one Client parameter. This ensures scripts can only interact with the DatoCMS API through the provided client.

3. Type safety: Scripts cannot use any or unknown types, preventing type-unsafe operations.

4. AST-level validation: The TypeScript compiler API validates the script's structure before any code execution.

For implementation details, see src/lib/scripts/validation.ts.

API token security

• Store tokens as environment variables, never in code or configuration files committed to repositories

• Use read-only tokens if you only need to retrieve content

• Limit token permissions to only what's required for your use case

• Rotate tokens regularly and revoke unused tokens

Troubleshooting

Server not connecting

1. Verify Node.js version is 18 or newer: node --version

2. Check that npx is available: which npx

3. Ensure your MCP client configuration is correct

4. Restart your IDE or client after configuration changes

API token issues

1. Verify the token is correct in your DatoCMS project settings

2. Check that the token has the necessary permissions

3. Ensure there are no extra quotes or spaces around the token in your configuration

4. Test the token in the DatoCMS API playground

Tools not appearing

1. Check if the server is running in your MCP client's server list

2. Review server logs for errors (method varies by client)

3. Verify network access to DatoCMS endpoints

4. For Claude Code, use: claude mcp logs datocms

5. For Claude Desktop, check the Developer tools console

Script execution failures

1. Review the validation errors - they indicate specific issues with script structure

2. Ensure you're using the correct TypeScript syntax

3. Verify all imports are from allowed packages

4. Check that the function signature matches the required format

5. Make sure you've called the appropriate documentation tools before using API methods

Performance issues

If operations are taking too long:

1. Switch to Claude Code: If you're using Claude Desktop and experiencing lag, switch to Claude Code for significantly better performance

2. Consider breaking very complex tasks into smaller steps

3. Use more specific prompts to reduce exploration time

4. Increase timeout limits if operations are timing out: set EXECUTION_TIMEOUT_SECONDS environment variable

5. Check if you can use simpler API methods for your use case

Client-specific issues

Claude Desktop lag/freezing:

• This is a known issue with Claude Desktop when using MCP servers

• Solution: Switch to Claude Code for a much better experience

• Claude Code handles the same MCP with fast, responsive performance

ChatGPT Codex slower performance:

• ChatGPT Codex works reliably but may be slower than Claude Code

• This is normal and doesn't indicate a problem

• Operations will still complete successfully

Feedback & Contributing

We value your feedback to improve the DatoCMS MCP server:

• Report issues: Open an issue on GitHub

• Share your experience: Let us know what works well and what doesn't

• Suggest improvements: Tell us about use cases that succeed or fail

• Contact us: Reach out at support@datocms.com

Your feedback helps us identify common issues, improve documentation, and enhance the server's capabilities.