This documentation is automatically synchronized from the core repository.View on GitHub

MCP Server

The dotCMS MCP (Model Context Protocol) Server enables AI assistants to interact directly with dotCMS content management capabilities. This powerful integration allows AI tools like Claude, GPT, and others to discover content schemas, create content types, manage content workflows, and perform complex content operations—all through natural language interactions.

When to Use It:#

Building AI-powered content management workflows
Automating content creation and publishing processes
Creating intelligent content discovery and search experiences
Developing AI assistants that need to understand your content structure
Implementing automated content operations and bulk updates

Key Benefits:#

Conversational Content Management: Ask AI to create, edit, and publish content using natural language instead of navigating through admin interfaces
Intelligent Content Discovery: Let AI understand your content structure and help you find, organize, and manage content across your site
Automated Publishing Workflows: Have AI handle content approval, publishing, and archiving based on your business rules
Smart Content Creation: Generate content that follows your existing content types and field requirements automatically
Bulk Content Operations: Process multiple pieces of content at once through simple AI conversations
Developer Productivity: Generate code components, forms, and integrations based on your actual dotCMS content structure

Prerequisites & Setup #

Get a dotCMS Environment #

Version Compatibility #

Recommended: dotCMS Evergreen
Minimum: dotCMS v24.4
Best Experience: Latest Evergreen release

Environment Setup #

For Production Use:

☁️ Cloud hosting options - managed solutions with SLA
🛠️ Self-hosted options - deploy on your infrastructure

For Testing & Development:

🧑🏻‍💻 dotCMS demo site - perfect for trying out the MCP server
📘 Learn how to use the demo site

For Local Development:

🐳 Docker setup guide
💻 Local installation guide

Create a dotCMS API Token #

[!WARNING] This MCP server requires an API token with write permissions for Content Types, Content, and Workflows. Only use tokens with the minimum required permissions and secure them properly.

This integration requires an API Token with content management permissions:

Go to the dotCMS admin panel
Click on System > Users
Select the user (with proper permissions) you want to create the API Token for
Go to API Access Key and generate a new key

For detailed instructions, please refer to the dotCMS API Documentation.

Configuration #

Before setting up the MCP server, you need these environment variables to connect to your dotCMS instance:

Environment Variables #

Variable	Required	Description	Example
`DOTCMS_URL`	✅	Your dotCMS instance URL	`https://demo.dotcms.com`
`AUTH_TOKEN`	✅	API authentication token (created in setup step)	`your-api-token-here`
`VERBOSE`	❌	Enable detailed logging for troubleshooting	`true`

Quickstart #

Get up and running with the dotCMS MCP Server in minutes:

Claude Desktop Setup #

Add the MCP server to your Claude Desktop configuration file. The configuration file location varies by operating system:

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

{
    "mcpServers": {
        "dotcms": {
            "command": "npx",
            "args": ["-y", "@dotcms/mcp-server"],
            "env": {
                "DOTCMS_URL": "https://your-dotcms-instance.com",
                "AUTH_TOKEN": "your-auth-token"
            }
        }
    }
}

Cursor IDE Setup #

Add the MCP server to your Cursor configuration. Open Cursor Settings and navigate to "Features" > "Model Context Protocol" or create/edit the configuration file:

{
    "mcpServers": {
        "dotcms": {
            "command": "npx",
            "args": ["-y", "@dotcms/mcp-server"],
            "env": {
                "DOTCMS_URL": "https://your-dotcms-instance.com",
                "AUTH_TOKEN": "your-auth-token"
            }
        }
    }
}

Start Using #

Restart your AI assistant (Claude Desktop or Cursor)
Start creating: Ask the AI to create content, manage workflows, or generate code

Example interactions:

You: "Create a new blog post about AI in content management"
AI: [Automatically learns your content structure and creates the blog post]

You: "Show me all my content types"
AI: [Discovers and displays your content schemas]

You: "Generate a React component for my Product content type"
AI: [Analyzes your Product fields and generates a complete component]

Available Tools #

The dotCMS MCP Server provides four core tools that enable comprehensive content management through AI:

Tool: context_initialization

Purpose: Must be called first to discover all available content types, sites, and workflow schemes

You: "Learn about my dotCMS setup"
AI: [Calls context_initialization and learns your complete content schema]

What it provides:

Complete list of content types with field definitions
Current site information
Available workflow schemes
Caches results for 30 minutes to optimize performance

Content Type Management #

Tools: content_type_list, content_type_create

Purpose: Discover and create content type schemas

You: "Show me all my content types"
AI: [Calls content_type_list to display your content schemas]

You: "Create a new Product content type with name, price, and description fields"
AI: [Calls content_type_create with the appropriate schema]

Capabilities:

List and filter existing content types
Create new content types with custom fields
Support for all dotCMS field types (Text, Image, Date, etc.)

Content Operations #

Tools: content_save, content_action

Purpose: Create, update, and manage content through workflow actions

You: "Create a new blog post about dotCMS MCP integration"
AI: [Calls content_save to create the content]

You: "Publish the blog post we just created"
AI: [Calls content_action with PUBLISH action]

Supported Actions:

Save: Create or update content
Publish: Make content live
Unpublish: Remove from live site
Archive: Move to archive state
Delete: Permanently remove content

Content Search #

Tool: content_search

Purpose: Query content using Lucene syntax

You: "Find all blog posts published this year that mention 'AI'"
AI: [Calls content_search with appropriate Lucene query]

Search Capabilities:

Full Lucene query syntax support
Filter by content type, date ranges, field values
Wildcard and fuzzy search
Boolean operators (AND, OR, NOT)

Development #

Local Development Setup #

For developers who want to contribute or modify the MCP server:

1. Clone and Setup #

# Clone the dotCMS repository
git clone https://github.com/dotCMS/core.git
cd core/core-web

# Install dependencies
yarn install

# Build the server
yarn nx build mcp-server

[!NOTE] Files are located in core-web/apps/mcp-server and we use Nx monorepo

2. Use Local Build in AI Assistants #

Claude Desktop Configuration:

{
    "mcpServers": {
        "dotcms": {
            "command": "node",
            "args": ["/path/to/dotcms/core/core-web/dist/apps/mcp-server/main.js"],
            "env": {
                "DOTCMS_URL": "your-dotcms-url",
                "AUTH_TOKEN": "your-auth-token"
            }
        }
    }
}

Cursor IDE Configuration:

{
    "mcpServers": {
        "dotcms": {
            "command": "node",
            "args": ["/path/to/dotcms/core/core-web/dist/apps/mcp-server/main.js"],
            "env": {
                "DOTCMS_URL": "your-dotcms-url",
                "AUTH_TOKEN": "your-auth-token"
            }
        }
    }
}

Project Structure #

mcp-server/
├── src/
│   ├── main.ts              # Entry point and server initialization
│   ├── services/            # HTTP clients for dotCMS APIs
│   │   ├── client.ts        # Base authenticated HTTP client
│   │   ├── contentype.ts    # Content type operations
│   │   ├── workflow.ts      # Content workflow actions
│   │   ├── search.ts        # Content search functionality
│   │   └── site.ts          # Site information
│   ├── tools/               # MCP tool implementations
│   │   ├── context/         # Context initialization
│   │   ├── content-types/   # Content type management
│   │   ├── workflow/        # Content operations
│   │   └── search/          # Search functionality
│   ├── types/               # TypeScript type definitions
│   └── utils/               # Shared utilities
├── jest.config.ts           # Test configuration
└── project.json             # Nx project configuration

Key Architecture Patterns #

Service Layer: All services extend AgnosticClient which provides:

Automatic authentication with Bearer tokens
Environment variable validation
Comprehensive error logging
Structured request/response handling

Tool Registration: Each tool module exports a registration function that:

Defines tool schema with Zod validation
Implements handlers with proper error handling
Returns structured MCP responses

Type Safety: Extensive use of Zod schemas for:

Runtime input validation
TypeScript type generation
API response validation

Development Commands #

# Build for development
yarn nx build mcp-server

# Lint the code
yarn nx lint mcp-server

# Serve in development mode
yarn nx serve mcp-server

# Run all tests
yarn nx test mcp-server

# Run tests in watch mode
yarn nx test mcp-server --watch

# Run with coverage
yarn nx test mcp-server --coverage

Contributing Guidelines #

When adding new MCP tools:

Create the tool in the appropriate src/tools/ subdirectory
Define Zod schemas for input validation
Implement proper error handling
Add comprehensive logging
Register the tool in src/main.ts
Add tests and documentation

Development Guidelines:

Follow TypeScript best practices: Use strict typing and proper interfaces
Add comprehensive tests: Include unit tests for new functionality
Document your changes: Update documentation for new features
Use Zod validation: All inputs and outputs should be validated
Follow logging patterns: Use the Logger class for consistent logging

Security Best Practices #

API Token Security #

Principle of Least Privilege: Only grant permissions required for your use case
Environment Variables: Never hardcode tokens in source code
Token Rotation: Regularly rotate API tokens
Monitoring: Monitor API usage for unusual patterns
HTTPS Only: Always use HTTPS for dotCMS connections

Logging and Monitoring #

The MCP server includes comprehensive logging:

Structured Logging: All operations logged with context
Error Tracking: Detailed error information with stack traces
Request/Response Logging: Full API interaction logging in verbose mode
Performance Monitoring: Request timing and performance metrics

dotCMS Support #

We offer multiple channels to get help with the dotCMS MCP Server:

GitHub Issues: For bug reports and feature requests, please open an issue in the GitHub repository
Community Forum: Join our community discussions to ask questions and share solutions
Documentation: Join our community discussions to ask questions and share solutions

When reporting issues, please include:

MCP server version and build information
dotCMS version and environment details
AI assistant being used (Claude, Cursor, etc.)
Minimal reproduction steps
Expected vs. actual behavior
Relevant log output

How To Contribute #

GitHub pull requests are the preferred method to contribute code to dotCMS. We welcome contributions to the dotCMS MCP Server! If you'd like to contribute, please follow these steps:

Fork the repository dotCMS/core
Create a feature branch (git checkout -b feature/amazing-mcp-feature)
Make your changes in the apps/mcp-server directory
Add tests for new functionality
Run the test suite (yarn nx test mcp-server)
Commit your changes (git commit -m 'Add amazing MCP feature')
Push to the branch (git push origin feature/amazing-mcp-feature)
Open a Pull Request

Development Guidelines #

Follow TypeScript best practices: Use strict typing and proper interfaces
Add comprehensive tests: Include unit tests for new functionality
Document your changes: Update documentation for new features
Use Zod validation: All inputs and outputs should be validated
Follow logging patterns: Use the Logger class for consistent logging

Adding New Tools #

When adding new MCP tools:

Create the tool in the appropriate src/tools/ subdirectory
Define Zod schemas for input validation
Implement proper error handling
Add comprehensive logging
Register the tool in src/main.ts
Add tests and documentation

Licensing Information #

dotCMS comes in multiple editions and as such is dual-licensed. The dotCMS Community Edition is licensed under the GPL 3.0 and is freely available for download, customization, and deployment for use within organizations of all stripes. dotCMS Enterprise Editions (EE) adds several enterprise features and is available via a supported, indemnified commercial license from dotCMS. For the differences between the editions, see the feature page.

This MCP Server is part of dotCMS's dual-licensed platform (GPL 3.0 for Community, commercial license for Enterprise).

Learn more at dotcms.com.

Source: core-web/apps/mcp-server/README.md

Branch: main

Found an issue with this documentation? Report it on GitHub