Installation | Directus Docs

Get AI assistants connected to your Directus instance in three simple steps. The MCP server is built into Directus with no additional setup required.

MCP is currently in Beta and requires Directus v11.12+. For older versions, use the Local MCP alternative.

Quick Setup

Enable MCP in Directus

Log into your Directus admin as an administrator
Go to Settings → AI → Model Context Protocol
Click Enable to activate the MCP server

Most users can keep the default settings. The MCP server is now ready at https://your-directus-url.com/mcp.

Generate Access Token

Navigate to User Directory
Click Create User with these settings:
- Email: ai-assistant@yourcompany.com (or similar)
- Role: Create a new role or use existing role with appropriate permissions
Generate an access token:
- Open the user profile
- Scroll to Token field → Generate new token
- Copy the token (you'll need it next)
- Save the user

Connect Your AI Client

Choose your AI tool and follow the setup:

Download Claude Desktop
Open Settings → Developer → Edit Config
Add this configuration:

{
  "mcpServers": {
    "directus": {
      "command": "mcp",
      "args": ["--server", "https://your-directus-url.com/mcp"],
      "env": {
        "DIRECTUS_TOKEN": "your-generated-token"
      }
    }
  }
}

Replace your-directus-url.com with your Directus URL
Replace your-generated-token with your user token
Restart Claude Desktop

Download Cursor
Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "directus": {
      "command": "mcp",
      "args": ["--server", "https://your-directus-url.com/mcp"],
      "env": {
        "DIRECTUS_TOKEN": "your-generated-token"
      }
    }
  }
}

Replace URLs and tokens
Verify connection in Settings → MCP

Install the Claude Code extension in VS Code
Open VS Code Settings and search for "Claude"
Find MCP Servers configuration
Add this configuration:

{
  "claude.mcpServers": {
    "directus": {
      "command": "mcp",
      "args": ["--server", "https://your-directus-url.com/mcp"],
      "env": {
        "DIRECTUS_TOKEN": "your-generated-token"
      }
    }
  }
}

Replace URLs and tokens with your values
Restart VS Code

Install the VS Code GitHub Copilot extension if not already installed
Open VS Code Settings and search for "copilot mcp"
Find GitHub Copilot: MCP Servers configuration
Add this configuration:

{
  "github.copilot.chat.mcpServers": {
    "directus": {
      "command": "mcp",
      "args": ["--server", "https://your-directus-url.com/mcp"],
      "env": {
        "DIRECTUS_TOKEN": "your-generated-token"
      }
    }
  }
}

Replace URLs and tokens with your values
Restart VS Code

Download Raycast
Search "MCP Servers" → "Install Server"
Paste configuration:

{
  "mcpServers": {
    "directus": {
      "command": "mcp",
      "args": ["--server", "https://your-directus-url.com/mcp"],
      "env": {
        "DIRECTUS_TOKEN": "your-generated-token"
      }
    }
  }
}

Press ⌘ + Enter to install
Use @directus to interact with your instance

Verify Connection

Test your setup with a simple question:

I have this blog post in Google Docs about AI trends in 2024. Can you import it as a new article in my blog collection?

I'll help you import that article. Let me first check your blog collection structure to understand the available fields... I can see you have fields for title, content, author, category, tags, and published_date. Please share the Google Doc content and I'll create a properly formatted blog post entry with the correct relationships.

User Permissions

Configure your AI user's role based on what you want them to do:

Content Editor Role (recommended for most users):

Collections: Read/Create/Update on your content collections
Files: Read/Create/Update/Delete
Folders: Read/Create/Update/Delete
System Collections: Read only

Developer Role (required for schema management):

All content permissions above, plus:
Collections: Full CRUD access
Fields: Full CRUD access
Relations: Full CRUD access
Flows: Full CRUD access

MCP Server Settings

Access advanced options in Settings → AI → Model Context Protocol:

Setting	Type	Default	Description
MCP Server	Toggle	Disabled	Connect AI/LLM tools to your Directus project via Model Context Protocol (MCP). This enables AI assistants to read and interact with your Directus data securely.
Allow Deletes	Toggle	Disabled	Enable deletion of items, files, flows, fields, relations, and collections through MCP tools. WARNING: May cause data loss. Disabled by default for safety.
AI Prompts Collection	Select	No collection selected	Select a collection to enable reusable prompt templates. Select existing collection or click "Generate AI Prompts collection..." to create one automatically.
Use System Prompt	Toggle	Enabled	Use the default system prompt to guide LLM behavior. Disable to remove or override with your own prompt below.
Custom System Prompt	Rich Text	Empty	Custom system prompt to replace the default. Leave empty to use default (if enabled above).

Next Steps

Your MCP server is ready! Here's what to explore:

See What's Possible

Real examples of AI-powered content workflows that save hours of manual work.

Available Tools

Complete reference of MCP tools and their capabilities.

Custom Prompts

Create reusable prompt templates for consistent AI interactions.

Security Guide

Essential security practices for using MCP safely with your Directus data.

Troubleshooting

Common issues and solutions when setting up and using the Directus MCP server.

Get once-a-month release notes & real‑world code tips...no fluff. 🐰

Overview

Connect AI assistants directly to your Directus instance. Let Claude, ChatGPT, and other AI tools read and write your content without manual copy-pasting.

Use Cases

Real examples of how to use AI with your Directus content to save time and reduce repetitive work.