Directus MCP server for AI agents

The Directus MCP Server extension implements the Model Context Protocol standard, allowing AI tools and LLMs to communicate with your Directus instance. This enables content editing, data analysis, and other interactions with your Directus project through natural language, while preventing potentially destructive operations.

Installation Requirements

Prerequisites

An existing Directus project

If you don't have a Directus project yet, you can:

Start a free trial on Directus Cloud
Create a local instance with:
```
npx directus-template-cli@latest init
```

Setting Up Directus Credentials

You'll need to authenticate the MCP server with your Directus instance using either email/password or a static token.

To generate a static access token:

Log in to your Directus instance
Navigate to User Directory and select your user profile
Scroll to the Token field
Generate and copy the token
Save your user profile (important!)

Connecting to AI Tools

Direct Connection with Claude Desktop

For Claude Desktop with remote MCP support:

Open Claude Desktop and go to Settings
Under the Developer tab, click Edit Config

Add this configuration:

{
  "mcpServers": {
    "directus": {
      "url": "https://YOUR_DIRECTUS_URL/directus-extension-mcp/mcp?access_token=YOUR_ACCESS_TOKEN"
    }
  }
}

Replace YOUR_DIRECTUS_URL and YOUR_ACCESS_TOKEN with your actual values
Save and restart Claude Desktop
The Directus MCP server should appear in new chats

Using mcp-remote for Other Clients

For AI tools without native remote support:

Configure your client to use mcp-remote:

Claude Desktop configuration:

{
  "mcpServers": {
    "directus": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://YOUR_DIRECTUS_URL/directus-extension-mcp/mcp?access_token=YOUR_ACCESS_TOKEN"
      ]
    }
  }
}

Cursor configuration:

{
  "mcpServers": {
    "directus": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://YOUR_DIRECTUS_URL/directus-extension-mcp/mcp?access_token=YOUR_ACCESS_TOKEN"
      ]
    }
  }
}

Replace the placeholders with your actual values
Save and restart your client
The server should now be available for use

Available Tools

The MCP Server provides various tools for interacting with Directus:

Tool	Description	Use Cases
system-prompt	Provides context about the assistant's role	Understanding system context
users-me	Get current user information	Understanding permissions
read-collections	Retrieve schema of all collections	Exploring database structure
read-items	Fetch items from any collection	Retrieving content, searching data
create-item	Create new items in collections	Adding new content or records
update-item	Modify existing items	Editing content, updating information
delete-item	Remove items from collections	Removing outdated content
read-files	Access file metadata or content	Finding images or media assets
import-file	Import files from URLs	Adding external media
update-files	Update file metadata	Organizing media, adding descriptions
read-fields	Get field definitions	Understanding data structure
read-field	Get specific field information	Viewing detailed field configuration
create-field	Add new fields to collections	Extending data models
update-field	Modify existing fields	Changing field configuration
read-flows	List available automation flows	Finding automation opportunities
trigger-flow	Execute automation flows	Bulk operations, publishing
read-comments	View comments on items	Retrieving feedback
upsert-comment	Add or update comments	Providing feedback
markdown-tool	Convert between markdown and HTML	Content formatting
get-prompts	List available prompts	Discovering prompt templates
get-prompt	Execute a stored prompt	Using prompt templates

Customizing the Server

System Prompt Configuration

The default system prompt provides guidance for the LLM. You can:

Override it by setting the MCP_SYSTEM_PROMPT environment variable in your Directus configuration
Disable it completely by setting MCP_SYSTEM_PROMPT_ENABLED to false

Prompt Collection Setup

For storing dynamic prompts in a Directus collection:

Configure these environment variables:

DIRECTUS_PROMPTS_COLLECTION_ENABLED: Set to "true" to enable
DIRECTUS_PROMPTS_COLLECTION: Collection name for prompts
DIRECTUS_PROMPTS_NAME_FIELD: Field for prompt name (default: "name")
DIRECTUS_PROMPTS_DESCRIPTION_FIELD: Field for description (default: "description")
DIRECTUS_PROMPTS_SYSTEM_PROMPT_FIELD: Field for system prompt text (default: "system_prompt")
DIRECTUS_PROMPTS_MESSAGES_FIELD: Field for messages array (default: "messages")

Using Mustache Templates

Both system prompts and messages support mustache templating:

Define variables using {{ variable_name }} syntax
Provide values in the arguments parameter when calling a prompt
Variables will be automatically replaced with provided values

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "directus" '{"command":"npx","args":["mcp-remote","https://YOUR_DIRECTUS_URL/directus-extension-mcp/mcp?access_token=YOUR_ACCESS_TOKEN"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "directus": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://YOUR_DIRECTUS_URL/directus-extension-mcp/mcp?access_token=YOUR_ACCESS_TOKEN"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration 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. Add this to your configuration file:

{
    "mcpServers": {
        "directus": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://YOUR_DIRECTUS_URL/directus-extension-mcp/mcp?access_token=YOUR_ACCESS_TOKEN"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect