Django CMS MCP Server Plugin

A Django CMS plugin that provides Model Context Protocol (MCP) server functionality, enabling AI assistants like Claude to directly interact with, manage, and create content in your Django CMS installation through natural language.

🚀 Features

• Complete CMS Integration: Full access to Django CMS pages, plugins, and templates
• LLM-Powered Content Management: Create, edit, and publish content through natural language
• Multi-language Support: Work with content in multiple languages seamlessly
• Plugin System Integration: Add and configure any Django CMS plugin via MCP
• Hierarchical Page Management: Navigate and manage complex page structures
• Template Management: Create pages with any available template
• Search & Discovery: Find content across your entire CMS
• Publishing Workflow: Draft, review, and publish content with proper workflow (djangocms-versioning required)
• Security First: Built-in authentication and permission checking

🎯 Use Cases

• Content Creation: "Create a new blog post about Django best practices"
• Site Management: "Update the homepage banner and publish the changes"
• Content Organization: "Move the pricing page under the products section"
• Multi-language Sites: "Translate this page to Spanish and French"
• Plugin Management: "Add a contact form to the about page"
• SEO Optimization: "Update meta descriptions for all product pages"

📦 Installation

1. Install the Package

pip install djangocms-mcp

2. Add to Django Settings

# settings.py
INSTALLED_APPS = [
   # existing apps...
    'cms',
    'menus',
    'treebeard',
    'sekizai',
    'easy_thumbnails',
    # ...
    'django_cms_mcp',  # Add this line
    # ... your other apps
]

# Optional: Configure MCP settings
DJANGO_CMS_MCP = {
    'REQUIRE_AUTHENTICATION': True,
    'ALLOWED_HOSTS': ['localhost', '127.0.0.1'],
    'MAX_PLUGINS_PER_REQUEST': 50,
    'ENABLE_SEARCH': True,
    'DEBUG_MODE': False,
}

3. Include URLs

# urls.py
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path("", include('mcp_server.urls')), # Be sure to include django-mcp-server urls!
    path('', include('cms.urls')),
]

4. Run Migrations

python manage.py migrate djangocms-mcp

🤖 Connecting to Claude Desktop

Configure Claude Desktop MCP Settings

To connect Claude Desktop to your Django CMS MCP server, you need to configure the MCP settings in Claude Desktop's configuration file.

1. Locate Claude Desktop Config File

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

2. Configure the MCP Server

Add your Django CMS MCP server to the configuration file:

{
  "mcpServers": {
    "django-cms": {
      "command": "python",
      "args": [
        "/path/to/your/project/manage.py",
        "start_mcp_server",
        "--host",
        "localhost",
        "--port",
        "8001"
      ],
      "env": {
        "DJANGO_SETTINGS_MODULE": "myproject.settings"
      }
    }
  }
}

3. Alternative: HTTP-based Configuration

If you prefer to run the server separately and connect via HTTP:

{
  "mcpServers": {
    "django-cms": {
      "command": "curl",
      "args": [
        "-X",
        "POST",
        "-H",
        "Content-Type: application/json",
        "http://localhost:8000/mcp/"
      ]
    }
  }
}

4. Production Configuration Example

For production environments with authentication:

{
  "mcpServers": {
    "django-cms-production": {
      "command": "python",
      "args": [
        "/var/www/mysite/manage.py",
        "start_mcp_server",
        "--host",
        "127.0.0.1",
        "--port",
        "8001"
      ],
      "env": {
        "DJANGO_SETTINGS_MODULE": "mysite.settings.production",
        "DATABASE_URL": "postgresql://user:pass@localhost/mydb",
        "SECRET_KEY": "your-secret-key-here"
      }
    }
  }
}

5. Restart Claude Desktop

After updating the configuration file:

1. Close Claude Desktop completely
2. Restart Claude Desktop
3. Verify the connection by asking Claude to interact with your CMS

6. Test the Connection

Once configured, you can test the connection by asking Claude:

"Can you show me the page structure of my Django CMS site?"

Claude will use the get_page_tree function to retrieve and display your site's page hierarchy.

💻 VS Code Integration

Installing Claude Extension for VS Code

1. Install the Extension:

   • Open VS Code
   • Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
   • Search for "Claude" by Anthropic
   • Click Install

2. Configure MCP Settings in VS Code:

Create or edit .vscode/settings.json in your project:

{
  "claude.mcpServers": {
    "django-cms": {
      "command": "python",
      "args": [
        "${workspaceFolder}/manage.py",
        "start_mcp_server",
        "--host",
        "localhost",
        "--port",
        "8001"
      ],
      "env": {
        "DJANGO_SETTINGS_MODULE": "${workspaceFolderBasename}.settings",
        "PYTHONPATH": "${workspaceFolder}"
      }
    }
  }
}

3. Workspace-Specific Configuration:

For multi-project workspaces, create .vscode/claude.config.json:

{
  "mcpServers": {
    "django-cms-dev": {
      "command": "${workspaceFolder}/venv/bin/python",
      "args": [
        "${workspaceFolder}/manage.py",
        "start_mcp_server"
      ],
      "env": {
        "DJANGO_SETTINGS_MODULE": "myproject.settings.development"
      },
      "cwd": "${workspaceFolder}"
    }
  }
}

4. Docker Development Setup:

If using Docker for development:

{
  "claude.mcpServers": {
    "django-cms-docker": {
      "command": "docker",
      "args": [
        "exec",
        "django-cms-container",
        "python",
        "manage.py",
        "start_mcp_server",
        "--host",
        "0.0.0.0",
        "--port",
        "8001"
      ]
    }
  }
}

VS Code Development Workflow

1. Content Creation Workflow

Open VS Code Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and use:

• "Claude: Ask about Django CMS" - Get information about your site structure
• "Claude: Create CMS Content" - Generate new pages and content
• "Claude: Review Page Structure" - Analyze your site organization

2. Code Integration

Create a VS Code task in .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Start Django CMS MCP Server",
      "type": "shell",
      "command": "python",
      "args": ["manage.py", "start_mcp_server"],
      "group": "build",
      "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": false,
        "panel": "shared"
      },
      "runOptions": {
        "runOn": "folderOpen"
      }
    }
  ]
}

3. Debug Configuration

Add to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Django CMS MCP Server",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/manage.py",
      "args": ["start_mcp_server", "--host", "localhost", "--port", "8001"],
      "django": true,
      "console": "integratedTerminal"
    }
  ]
}

4. Integrated Terminal Commands

Use VS Code's integrated terminal for quick MCP operations:

# Start the MCP server
python manage.py start_mcp_server

# Test MCP functions directly
python manage.py shell
>>> from django_cms_mcp.mcp_server import DjangoCMSMCPServer
>>> server = DjangoCMSMCPServer()
>>> # Test functions here

VS Code Snippets for Django CMS MCP

Create .vscode/snippets/djangocms-mcp.json:

{
  "MCP Create Page": {
    "prefix": "mcp-create-page",
    "body": [
      "# Ask Claude to create a page",
      "# Example: \"Create a ${1:page-type} page titled '${2:Page Title}' using the ${3:template-name} template\""
    ],
    "description": "Template for asking Claude to create a CMS page"
  },
  "MCP Add Plugin": {
    "prefix": "mcp-add-plugin",
    "body": [
      "# Ask Claude to add content",
      "# Example: \"Add a ${1:plugin-type} plugin to the ${2:placeholder-name} placeholder on page ${3:page-id}\""
    ],
    "description": "Template for asking Claude to add a plugin"
  },
  "MCP Search Content": {
    "prefix": "mcp-search",
    "body": [
      "# Ask Claude to find content",
      "# Example: \"Find all pages containing '${1:search-term}' in ${2:language}\""
    ],
    "description": "Template for content search via Claude"
  }
}

VS Code Extensions Compatibility

The Django CMS MCP server works well with these VS Code extensions:

• Python Extension Pack - Enhanced Python development
• Django Extension - Django-specific features
• REST Client - Test MCP HTTP endpoints
• Thunder Client - API testing for MCP endpoints
• Database Client - View CMS database content

VS Code Project Template

Create a complete VS Code workspace template:

djangocms-mcp.code-workspace:

{
  "folders": [
    {
      "path": "."
    }
  ],
  "settings": {
    "python.defaultInterpreterPath": "./venv/bin/python",
    "django.settingsModule": "myproject.settings",
    "claude.mcpServers": {
      "django-cms": {
        "command": "${workspaceFolder}/venv/bin/python",
        "args": ["${workspaceFolder}/manage.py", "start_mcp_server"],
        "env": {
          "DJANGO_SETTINGS_MODULE": "myproject.settings"
        }
      }
    }
  },
  "extensions": {
    "recommendations": [
      "ms-python.python",
      "batisteo.vscode-django",
      "anthropic.claude-vscode"
    ]
  }
}

Troubleshooting VS Code Integration

1. Extension Not Found

# Install Claude extension manually
code --install-extension anthropic.claude-vscode

2. Python Path Issues

{
  "python.defaultInterpreterPath": "./venv/bin/python",
  "python.terminal.activateEnvironment": true
}

3. Environment Variables

{
  "terminal.integrated.env.linux": {
    "DJANGO_SETTINGS_MODULE": "myproject.settings"
  },
  "terminal.integrated.env.osx": {
    "DJANGO_SETTINGS_MODULE": "myproject.settings"
  },
  "terminal.integrated.env.windows": {
    "DJANGO_SETTINGS_MODULE": "myproject.settings"
  }
}

Troubleshooting Connection Issues

Common Issues and Solutions

1. Server Not Starting

# Check if the management command works
python manage.py start_mcp_server --host localhost --port 8001

# Verify Django settings
python manage.py check

2. Permission Errors

• Ensure the user running Claude Desktop has execute permissions on your Python environment
• Check that Django database permissions are properly configured

3. Port Conflicts

# Check if port is available
netstat -an | grep 8001

# Use a different port if needed
python manage.py start_mcp_server --port 8002

4. Environment Variables

{
  "mcpServers": {
    "django-cms": {
      "command": "python",
      "args": ["/path/to/manage.py", "start_mcp_server"],
      "env": {
        "DJANGO_SETTINGS_MODULE": "myproject.settings",
        "PYTHONPATH": "/path/to/your/project",
        "PATH": "/path/to/your/venv/bin:$PATH"
      }
    }
  }
}

5. Virtual Environment Issues If using a virtual environment, specify the full path to Python:

{
  "mcpServers": {
    "django-cms": {
      "command": "/path/to/your/venv/bin/python",
      "args": [
        "/path/to/your/project/manage.py",
        "start_mcp_server"
      ]
    }
  }
}

Security Considerations for Claude Desktop

When connecting Claude Desktop to your Django CMS:

1. Use Local Connections: Keep the MCP server on localhost when possible
2. Limit Permissions: Create a dedicated Django user with minimal required permissions
3. Monitor Usage: Enable logging to track MCP requests
4. Firewall Rules: Ensure the MCP port is not exposed to external networks

# Example settings for Claude Desktop integration
DJANGO_CMS_MCP = {
    'REQUIRE_AUTHENTICATION': True,
    'ALLOWED_HOSTS': ['127.0.0.1', 'localhost'],
    'LOG_REQUESTS': True,
    'MAX_PLUGINS_PER_REQUEST': 25,  # Limit for safety
    'DEBUG_MODE': False,
}

Method 1: Django CMS Plugin (Recommended)

1. Add the Plugin:

   • Go to your Django CMS admin
   • Edit any page and add the "MCP Server" plugin
   • Configure the plugin settings (title, description, enable/disable)
   • Save and publish the page

2. Access the Server:

   • The MCP server is automatically available at /mcp/
   • The plugin displays current status and available functions

Method 2: Management Command

Start a standalone MCP server:

python manage.py start_mcp_server --host localhost --port 8001

Method 3: Programmatic Access

from django_cms_mcp.mcp_server import DjangoCMSMCPServer

# Initialize the server
server = DjangoCMSMCPServer()

# Use the server programmatically
response = server.get_server().handle_request({
    "method": "get_page_tree",
    "params": {"language": "en"}
})

🔧 MCP Functions Reference

📄 Page Management

Function	Description	Parameters
get_page_tree	Get hierarchical page structure	language (optional)
get_page	Retrieve full page content with plugins	page_id, language (optional)
create_page	Create a new page	title, template, language, slug, parent_id, meta_description
publish_page	Publish a page to make it live	page_id, language
search_pages	Search pages by title or content	query, language, published_only

🔌 Plugin Management

Function	Description	Parameters
list_plugin_types	Get available plugin types	None
create_plugin	Add a plugin to a placeholder	page_id, placeholder_slot, plugin_type, data, language, position
update_plugin	Update existing plugin content	plugin_id, data

🎨 Template & Structure

Function	Description	Parameters
list_templates	Get available CMS templates	None
get_languages	Get configured languages	None

💡 Example Usage with Claude

Creating Content

You: "Create a new blog post about Python web development with Django"

Claude: I'll create a new blog post for you about Python web development with Django.

# Claude uses these MCP calls:
create_page(
    title="Python Web Development with Django",
    template="blog_post.html",
    language="en",
    slug="python-web-development-django",
    meta_description="Complete guide to building web applications with Django framework"
)

create_plugin(
    page_id=123,
    placeholder_slot="content",
    plugin_type="TextPlugin",
    data={
        "body": "Django is a high-level Python web framework..."
    }
)

Managing Site Structure

You: "Move the pricing page under the products section and update its title"

Claude: I'll reorganize your site structure and update the page title.

# Claude finds the pages and restructures
search_pages(query="pricing")
search_pages(query="products")
# Then moves and updates the page

Multi-language Content

You: "Translate the homepage to Spanish"

Claude: I'll create a Spanish translation of your homepage.

get_page(page_id=1, language="en")  # Get English content
create_translation(page_id=1, target_language="es")  # Create Spanish version

🛡️ Security

The plugin implements multiple security layers:

• Authentication Required: All MCP endpoints require Django user authentication
• Permission Checking: Respects Django CMS page permissions
• CSRF Protection: Automatic CSRF token handling
• Input Validation: All inputs are validated and sanitized
• Rate Limiting: Configurable request limits (optional)

Production Security Checklist

• [ ] Use HTTPS in production
• [ ] Configure ALLOWED_HOSTS properly
• [ ] Set up proper authentication (OAuth, SAML, etc.)
• [ ] Enable logging and monitoring
• [ ] Regular security updates

⚙️ Configuration

Available Settings

# settings.py
DJANGO_CMS_MCP = {
    # Security
    'REQUIRE_AUTHENTICATION': True,
    'ALLOWED_HOSTS': ['localhost', '127.0.0.1'],
    'ALLOWED_ORIGINS': ['https://claude.ai'],
    
    # Performance
    'MAX_PLUGINS_PER_REQUEST': 50,
    'CACHE_TIMEOUT': 300,
    'ENABLE_COMPRESSION': True,
    
    # Features
    'ENABLE_SEARCH': True,
    'ENABLE_MEDIA_UPLOAD': True,
    'ENABLE_BULK_OPERATIONS': False,
    
    # Development
    'DEBUG_MODE': False,
    'LOG_REQUESTS': True,
    'VERBOSE_ERRORS': False,
}

Logging Configuration

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'mcp_file': {
            'level': 'INFO',
            'class': 'logging.FileHandler',
            'filename': 'mcp_server.log',
        },
    },
    'loggers': {
        'django_cms_mcp': {
            'handlers': ['mcp_file'],
            'level': 'INFO',
            'propagate': True,
        },
    },
}

🧪 Development

Setting Up Development Environment

# Clone the repository
git clone https://github.com/rsp2k/djangocms-mcp.git
cd djangocms-mcp

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

# Run tests with coverage
pytest --cov=django_cms_mcp --cov-report=html

Code Quality Tools

# Format code
black .
isort .

# Lint code
ruff check .
flake8

# Type checking
mypy django_cms_mcp

# Security check
bandit -r django_cms_mcp

Running Tests

# Run all tests
pytest

# Run specific test categories
pytest -m unit          # Unit tests only
pytest -m integration   # Integration tests only
pytest -m "not slow"    # Skip slow tests

# Run with different Django/Python versions
tox

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Start for Contributors

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Ensure all tests pass: pytest
5. Format your code: black . && isort .
6. Submit a pull request

Reporting Issues

• Use the GitHub issue tracker
• Include Django/Python versions
• Provide minimal reproduction steps
• Include relevant logs

📚 Documentation

• API Reference
• Configuration Guide
• Examples
• Troubleshooting

🗺️ Roadmap

Version 1.0 (Current) ✅

• [x] Support djangocms-versioning
• [x] Complete Django CMS page management
• [x] Plugin system integration with create/update/list operations
• [x] Multi-language support for all operations
• [x] Hierarchical page tree navigation
• [x] Template management and listing
• [x] Basic search functionality across pages
• [x] Publishing workflow (draft/live)
• [x] Authentication and permission checking
• [x] Django CMS plugin for easy integration
• [x] Management command for standalone server
• [x] HTTP endpoint for web-based MCP clients
• [x] Media/Filer integration support
• [x] Page extension field access
• [x] Content serialization and data handling

This project provides a complete, production-ready MCP server implementation for Django CMS. All core functionality needed for LLM-powered content management is included in the current version.

📄 License

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

🙏 Acknowledgments

• Django CMS Team - For the amazing CMS framework
• Anthropic - For the Model Context Protocol specification
• Django Community - For the robust web framework
• Contributors - Thank you to all contributors who help improve this project

📞 Support

• Documentation: https://djangocms-mcp.readthedocs.io/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: django-mcp@supported.systems

---

Made with ❤️ for the Django CMS and LLLMcommunity