Directus MCP Server

Directus MCP Server

A Model Context Protocol (MCP) server that provides comprehensive tools for managing Directus schema and content. This server enables AI assistants and other MCP clients to interact with Directus instances programmatically.

Installation

From npm (once published)

npm install -g directus-mcp-server

From source

git clone https://github.com/yourusername/directus-mcp.git
cd directus-mcp
npm install
npm run build

Features

• Schema Management: Create, read, update, and delete collections, fields, and relations
• Content Management: Full CRUD operations on items with advanced querying
• Type Safety: Built with TypeScript and Zod validation
• Official SDK: Uses the official @directus/sdk for reliable API interactions
• Flexible Authentication: Supports both static tokens and email/password authentication

Installation

npm install

Configuration

Create a .env file in the root directory with your Directus configuration:

# Directus Instance URL
DIRECTUS_URL=https://your-directus-instance.com

# Authentication - Use either token OR email/password
DIRECTUS_TOKEN=your_static_token_here

# Alternative: Email/Password authentication
# DIRECTUS_EMAIL=admin@example.com
# DIRECTUS_PASSWORD=your_password

Authentication Options

1. Static Token (Recommended for production):

   • Generate a static token in Directus Admin App
   • Set DIRECTUS_TOKEN environment variable

2. Email/Password:

   • Use for development or when static tokens aren't available
   • Set DIRECTUS_EMAIL and DIRECTUS_PASSWORD environment variables

Toolset Configuration

The Directus MCP server organizes tools into logical toolsets, similar to GitHub's MCP implementation. This allows you to control which tools are exposed to the MCP client.

Available Toolsets:

• default - Contains collections, fields, relations, and content tools (default behavior when no toolset is specified)
• collections - Collection management tools (list, get, create, update, delete collections)
• fields - Field management tools (list, create, update, delete fields)
• relations - Relation management tools (list, create, delete relations)
• schema - Schema snapshot and diff tools (get snapshot, get diff, apply diff) - NOT included in default toolset
• content - Content management tools (items CRUD operations)
• flow - Flow management tools (workflow automation) - NOT included in default toolset
• dashboards - Dashboard and panel management tools (list, get, create, update, delete dashboards and panels) - NOT included in default toolset
• all - All available tools regardless of toolset membership

Default Behavior: When MCP_TOOLSETS is not set or empty, only tools in the default toolset are exposed. The default toolset contains collections, fields, relations, and content tools, but not schema, flow, or dashboard tools. Schema, flow, and dashboard tools must be explicitly requested by including schema, flow, or dashboards in the MCP_TOOLSETS environment variable.

Configuration: Set the MCP_TOOLSETS environment variable to a comma-separated list of toolsets:

# Expose only collections tools
MCP_TOOLSETS=collections

# Expose only schema snapshot/diff tools
MCP_TOOLSETS=schema

# Expose collections and fields tools
MCP_TOOLSETS=collections,fields

# Expose only dashboard and panel tools
MCP_TOOLSETS=dashboards

# Expose all schema-related toolsets
MCP_TOOLSETS=collections,fields,relations,schema

# Expose all toolsets (includes flow and dashboard tools)
MCP_TOOLSETS=default,flow,dashboards
# OR
MCP_TOOLSETS=collections,fields,relations,schema,content,flow,dashboards
# OR simply use 'all' to expose everything
MCP_TOOLSETS=all

Examples:

{
  "mcpServers": {
    "directus-schema": {
      "command": "node",
      "args": ["/path/to/directus-mcp/dist/index.js"],
      "env": {
        "DIRECTUS_URL": "https://your-directus-instance.com",
        "DIRECTUS_TOKEN": "your_token",
        "MCP_TOOLSETS": "schema"
      }
    },
    "directus-content": {
      "command": "node",
      "args": ["/path/to/directus-mcp/dist/index.js"],
      "env": {
        "DIRECTUS_URL": "https://your-directus-instance.com",
        "DIRECTUS_TOKEN": "your_token",
        "MCP_TOOLSETS": "content"
      }
    }
  }
}

Notes:

• Toolset names are case-insensitive
• Invalid toolset names are ignored (with a warning)
• If all requested toolsets are invalid, the server defaults to the default toolset
• Collections, fields, relations, and content tools belong to both default and their specific toolset
• Schema, flow, and dashboard tools belong ONLY to their respective toolsets (not in default)

Building

npm run build

Usage

Running the Server

npm start

Or use the built binary:

node dist/index.js

MCP Client Configuration

Add to your MCP