home / mcp / directus mcp server

Directus MCP Server

Provides a Directus MCP server to query, create, update, and manage Directus data via natural language prompts.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "joshthederf-directus-extension-mcp": {
      "url": "https://YOUR_DIRECTUS_URL/directus-extension-mcp/mcp?access_token=YOUR_ACCESS_TOKEN",
      "headers": {
        "MCP_SYSTEM_PROMPT": "<MCP_SYSTEM_PROMPT>",
        "MCP_SYSTEM_PROMPT_ENABLED": "<MCP_SYSTEM_PROMPT_ENABLED>",
        "DIRECTUS_PROMPTS_COLLECTION": "<DIRECTUS_PROMPTS_COLLECTION>",
        "DIRECTUS_PROMPTS_NAME_FIELD": "<DIRECTUS_PROMPTS_NAME_FIELD>",
        "DIRECTUS_PROMPTS_MESSAGES_FIELD": "<DIRECTUS_PROMPTS_MESSAGES_FIELD>",
        "DIRECTUS_PROMPTS_DESCRIPTION_FIELD": "<DIRECTUS_PROMPTS_DESCRIPTION_FIELD>",
        "DIRECTUS_PROMPTS_COLLECTION_ENABLED": "<DIRECTUS_PROMPTS_COLLECTION_ENABLED>",
        "DIRECTUS_PROMPTS_SYSTEM_PROMPT_FIELD": "<DIRECTUS_PROMPTS_SYSTEM_PROMPT_FIELD>"
      }
    }
  }
}

The Directus MCP Server Extension lets any MCP client connect to your Directus instance, enabling content editors to manage content and data analysts to query collections through natural language. It provides safe, streaming HTTP communication and a curated set of tools to interact with Directus without risking destructive actions.

How to use

You connect an MCP client to your Directus instance using either a remote URL configuration or a local, npx-based bridge. Once connected, you can browse your Directus schema, read collections and items, manage files and fields, run automation flows, and interact with content through natural language prompts. The server limits destructive actions such as deleting fields or collections to protect your data while still offering powerful reading, creating, updating, and commenting capabilities.

How to install

Prerequisites you need before starting:

A Directus project ready to use

Install Directus extension and prepare credentials as described below.

Additional sections

MCP connection methods are provided for HTTP remote access and for local bridging via a command runner. The HTTP configuration uses a shared URL, while the local bridge uses a command that runs an MCP bridge client (for clients that lack native remote support). You can structure your setup to immediately connect and begin querying Directus data.

System prompts and prompts configuration

You can customize the system prompt for guiding the LLM’s tool usage by setting MCP_SYSTEM_PROMPT in your Directus environment. You can also disable it by setting MCP_SYSTEM_PROMPT_ENABLED to false. For prompts stored inside Directus, enable the prompts collection and set the corresponding field mappings to define names, descriptions, system prompts, and messages. You can use mustache templating to substitute variables in prompts with values you supply at call time.

Security and usage notes

The extension is designed to be safe by default, avoiding destructive changes. Always protect access tokens and use HTTPS URLs to prevent token leakage.

Tools exposed by the MCP server

The MCP server provides a comprehensive set of tools to interact with Directus data and metadata, including reading schema, reading and creating items, updating fields, managing files, and running automations. This enables you to perform content operations, data analysis, and workflow actions from MCP-enabled clients.

Available tools

system-prompt

Provides context to the LLM about its role and session start, guiding tool usage

users-me

Fetches current user information to tailor responses and permissions

read-collections

Retrieves the schema of all collections to explore structure and relationships

read-items

Fetches items from a collection for display or searching

create-item

Creates new items in collections to add content or records

update-item

Updates existing items to modify content or statuses

delete-item

Removes items from collections to clean up outdated content

read-files

Accesses file metadata or content to locate assets

import-file

Imports files from URLs to add external media

update-files

Updates file metadata for organization and tagging

read-fields

Gets field definitions for collections to understand data structure

read-field

Gets specific field information for detailed configuration

create-field

Adds new fields to collections to extend data models

update-field

Modifies existing fields including validation and UI options

read-flows

Lists available automation flows for discovery

trigger-flow

Executes automation flows for bulk operations or status changes

read-comments

Views comments on items to retrieve feedback and discussions

upsert-comment

Adds or updates comments to document decisions or feedback

markdown-tool

Converts between markdown and HTML for WYSIWYG fields

get-prompts

Lists available prompt templates for reuse

get-prompt

Executes a stored prompt template for consistent interactions