Model Context Protocol (MCP) server for dotCMS - enables AI agents to interact with dotCMS content management capabilities
npm install @dotcms/mcp-serverThe 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.
- 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
- 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
- Create a dotCMS API Token
- Quickstart
- Available Tools
- Context Initialization
- Content Type Management
- Content Operations
- Content Search
- Development
- Local Development Setup
- Project Structure
- Development Commands
- Contributing Guidelines
- Security Best Practices
- dotCMS Support
- How To Contribute
- Licensing Information
#### 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
> [!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:
1. Go to the dotCMS admin panel
2. Click on System > Users
3. Select the user (with proper permissions) you want to create the API Token for
4. Go to API Access Key and generate a new key
For detailed instructions, please refer to the dotCMS API Documentation.
Before setting up the MCP server, you need these environment variables to connect to your dotCMS instance:
| 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 |
| RESPONSE_MAX_LENGTH | β | Maximum character limit for response truncation (no truncation if not set) | 5000 |
The MCP server includes intelligent response truncation to manage large data responses and optimize performance. This feature is controlled by the RESPONSE_MAX_LENGTH environment variable:
Behavior:
- Not set or 0: No truncation occurs (unlimited response length)
- Positive number: Responses are truncated to the specified character limit
- Invalid value: No truncation occurs (falls back to unlimited)
When truncation occurs:
- Large content search results
- Extensive content type schemas
- Bulk content operations
- Any response exceeding the specified limit
Truncation format:
```
Original response content...
[truncated]
Get up and running with the dotCMS MCP Server in minutes:
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%APPDATA%\Claude\claude_desktop_config.json
- Windows:
`json`
{
"mcpServers": {
"dotcms": {
"command": "npx",
"args": ["-y", "@dotcms/mcp-server"],
"env": {
"DOTCMS_URL": "https://your-dotcms-instance.com",
"AUTH_TOKEN": "your-auth-token"
}
}
}
}
Add the MCP server to your Cursor configuration. Open Cursor Settings and navigate to "Features" > "Model Context Protocol" or create/edit the configuration file:
`json`
{
"mcpServers": {
"dotcms": {
"command": "npx",
"args": ["-y", "@dotcms/mcp-server"],
"env": {
"DOTCMS_URL": "https://your-dotcms-instance.com",
"AUTH_TOKEN": "your-auth-token"
}
}
}
}
1. Restart your AI assistant (Claude Desktop or Cursor)
2. 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]
`
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
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.)
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
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)
For developers who want to contribute or modify the MCP server:
#### 1. Clone and Setup
`bashClone the dotCMS repository
git clone https://github.com/dotCMS/core.git
cd core/core-web
> [!NOTE]
> Files are located in
core-web/apps/mcp-server and we use Nx monorepo#### 2. Use MCP Inspector for debug
After a succesful build
`bash
npx @modelcontextprotocol/inspector -e DOTCMS_URL=https://demo.dotcms.com -e AUTH_TOKEN=the-auth-token node dist/apps/mcp-server
`#### 3. Use Local Build in AI Assistants
Claude Desktop Configuration:
`json
{
"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:
`json
{
"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"
}
}
}
}
`$3
`
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
`$3
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
$3
`bash
Build for development
yarn nx build mcp-serverLint the code
yarn nx lint mcp-serverServe in development mode
yarn nx serve mcp-serverRun all tests
yarn nx test mcp-serverRun tests in watch mode
yarn nx test mcp-server --watchRun with coverage
yarn nx test mcp-server --coverage
`$3
When adding new MCP tools:
1. Create the tool in the appropriate
src/tools/ subdirectory
2. Define Zod schemas for input validation
3. Implement proper error handling
4. Add comprehensive logging
5. Register the tool in src/main.ts
6. Add tests and documentationDevelopment 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
$3
- 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
$3
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:
1. Fork the repository dotCMS/core
2. Create a feature branch (
git checkout -b feature/amazing-mcp-feature)
3. Make your changes in the apps/mcp-server directory
4. Add tests for new functionality
5. Run the test suite (yarn nx test mcp-server)
6. Commit your changes (git commit -m 'Add amazing MCP feature')
7. Push to the branch (git push origin feature/amazing-mcp-feature)
8. Open a Pull Request$3
- 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
$3
When adding new MCP tools:
1. Create the tool in the appropriate
src/tools/ subdirectory
2. Define Zod schemas for input validation
3. Implement proper error handling
4. Add comprehensive logging
5. Register the tool in src/main.ts`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.