MCP 服务器

djangocms-mcp

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.

README

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:

Close Claude Desktop completely
Restart Claude Desktop
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

Install the Extension:
- Open VS Code
- Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
- Search for "Claude" by Anthropic
- Click Install
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}"
      }
    }
  }
}

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

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:

Use Local Connections: Keep the MCP server on localhost when possible
Limit Permissions: Create a dedicated Django user with minimal required permissions
Monitor Usage: Enable logging to track MCP requests
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)

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

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

Reporting Issues

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

📚 Documentation

🗺️ 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