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 interact with your DatoCMS projects using natural language commands. Log in once via OAuth and work across every project you have access to in a single session.

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 projects 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 across multiple projects: Log in once via OAuth and switch between any project you have access to in the same session, without restarting the server or swapping environment variables

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 account (you will authenticate via OAuth on first use)

• 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

Below, we list the installation instructions for multiple popular IDEs and apps, but the above are the ones we have the most experience with and recommend.

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 -y @datocms/mcp@latest

ChatGPT Codex

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

codex mcp add datocms -- npx -y @datocms/mcp@latest

Cursor

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

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

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

Windsurf

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

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

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:

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

Restart Claude Desktop after saving.

Google Antigravity

In Antigravity Settings → Customizations → Installed MCP Servers, click the Open MCP Config button. You can also directly open or create the file ~/.gemini/antigravity/mcp_config.json and use this configuration:

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

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:

• 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:

• 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 login)

Execution layer - Tools that perform operations (require login):

• 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

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

• 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.

OAuth credential security

• OAuth credentials are stored locally at ~/.config/datocms-mcp/credentials.json with restrictive file permissions

• Use scoped access during the OAuth authorization step to limit which projects the MCP server can access

• Use datocms_logout to revoke tokens — this contacts the server to invalidate the token before removing local credentials

• Revoked or expired tokens are detected automatically and prompt a re-login

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

Authentication issues

1. Run datocms_login to re-authenticate if your token has been revoked or has expired

2. Use datocms_whoami to verify which account is currently logged in

3. Check that you granted access to the correct projects during the OAuth authorization step

4. Try datocms_logout followed by datocms_login to start a fresh session

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. Consider breaking very long-running operations into smaller steps

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.