Directus MCP Server

An MCP (Model Context Protocol) server that connects your AI assistant (Claude, Cursor, etc.) to a Directus instance. Ask your AI to read content, manage schema, create automation flows, and more — all through natural language.

Features

• Content Management — Read, create, and update items across your Directus collections
• Schema Management — Create and modify collections, fields, and relations
• Flow Automation — Build and trigger Directus flows with operations and conditions
• File Management — Read, update, and import files and assets
• User & Comments — Read users and manage comments on collection items
• Content Conversion — Convert between HTML and Markdown
• Prompt Management — Serve LLM prompts from a Directus collection (optional)
• Safe Defaults — Destructive operations (delete) are disabled by default
• Scoped Access — Exclude sensitive collections from AI access via configuration

Quick Start

Prerequisites

• A running Directus instance (Directus Cloud or self-hosted)
• A Directus API token or user credentials

Installation

Using npx (Recommended)

No installation needed. Add to your MCP client configuration (Claude Desktop / Claude Code / Cursor):

{
  "mcpServers": {
    "directus": {
      "command": "npx",
      "args": ["-y", "@archawat/mcp-directus"],
      "env": {
        "DIRECTUS_URL": "https://your-instance.com",
        "DIRECTUS_TOKEN": "your-token"
      }
    }
  }
}

Global Install

npm install -g @archawat/mcp-directus

Then configure your MCP client:

{
  "mcpServers": {
    "directus": {
      "command": "mcp-directus",
      "env": {
        "DIRECTUS_URL": "https://your-instance.com",
        "DIRECTUS_TOKEN": "your-token"
      }
    }
  }
}

Available Tools

Discovery

| Tool | Description | |------|-------------| | directus_help | Overview of available tools and token-efficiency guidance | | directus_list_collections | List all collection names (lightweight) | | directus_count_items | Count items in a collection without fetching data | | directus_get_item_summary | Quick summary of items with key fields only |

Schema

| Tool | Description | |------|-------------| | directus_read_collection_schema | Schema for a single collection (preferred) | | directus_read_collections | Full schema for all collections (large response — use sparingly) | | directus_create_collection | Create a new collection or folder |

Fields

| Tool | Description | |------|-------------| | directus_read_fields | All fields for a collection | | directus_read_field | A single field's details | | directus_create_field | Add a field to a collection | | directus_update_field | Modify an existing field |

Relations

| Tool | Description | |------|-------------| | directus_read_relations | List relations, optionally filtered by collection | | directus_read_relation | Details of a specific relation | | directus_create_relation | Create a relation (M2O, O2M, M2M, M2A) | | directus_update_relation | Update an existing relation | | directus_delete_relation | Delete a relation (disabled by default) |

Items

| Tool | Description | |------|-------------| | directus_read_items | Read items from a collection with filtering, sorting, and pagination | | directus_create_item | Create a new item (system collections protected by default) | | directus_update_item | Update an existing item (system collections protected by default) | | directus_delete_item | Delete an item (disabled by default) |

Flows

| Tool | Description | |------|-------------| | directus_read_flows | List all flows, optionally filtered by trigger type | | directus_read_flow | Details of a specific flow | | directus_create_flow | Create a new automation flow | | directus_update_flow | Update an existing flow | | directus_delete_flow | Delete a flow (disabled by default) | | directus_trigger_flow | Manually trigger a flow |

Operations (Flow Steps)

| Tool | Description | |------|-------------| | directus_read_operations | List operations, optionally filtered by flow | | directus_read_operation | Details of a specific operation | | directus_create_operation | Add an operation to a flow | | directus_update_operation | Modify an existing operation | | directus_delete_operation | Delete an operation (disabled by default) |

Users

| Tool | Description | |------|-------------| | directus_users_me | Current authenticated user info | | directus_read_users | Read user data with filtering and field selection |

Comments

| Tool | Description | |------|-------------| | directus_read_comments | Read comments on collection items | | directus_upsert_comment | Create or update a comment on an item |

Files & Assets

| Tool | Description | |------|-------------| | directus_read_files | Read file metadata or raw file content | | directus_update_files | Update file metadata (batch supported) | | directus_import_file | Import a file from a URL | | directus_read_folders | List file folders |

Utilities

| Tool | Description | |------|-------------| | directus_markdown | Convert between HTML and Markdown |

Prompts (Optional)

| Tool | Description | |------|-------------| | directus_system_prompt | Retrieve system prompt with operational guidelines (enabled by default) | | directus_get_prompts | Retrieve LLM prompts from a Directus collection (disabled by default) |

Configuration

Environment Variables

# Required — Directus instance URL
DIRECTUS_URL=https://your-instance.com

# Authentication (use token OR email/password)
DIRECTUS_TOKEN=your-token
[email protected]
DIRECTUS_USER_PASSWORD=password

# Disable specific tools (comma-separated, uses full tool names)
# Default: directus_delete_item
DISABLE_TOOLS=directus_delete_item,directus_delete_flow,directus_delete_operation,directus_delete_relation

# Exclude collections from AI access (comma-separated)
SCHEMA_EXCLUDE_COLLECTIONS=logs,cache,temp_data

# Allow modifying Directus system collections (disabled by default)
ALLOW_SYSTEM_MODIFICATIONS=false

# System prompt configuration
MCP_SYSTEM_PROMPT_ENABLED=true          # Enable the system prompt tool (default: true)
MCP_SYSTEM_PROMPT=                       # Custom system prompt override (optional)

# LLM Prompts collection (disabled by default)
DIRECTUS_PROMPTS_COLLECTION_ENABLED=false
DIRECTUS_PROMPTS_COLLECTION=prompts              # Collection name storing LLM prompts
DIRECTUS_PROMPTS_NAME_FIELD=name                 # Field for prompt name
DIRECTUS_PROMPTS_DESCRIPTION_FIELD=description   # Field for prompt description
DIRECTUS_PROMPTS_SYSTEM_PROMPT_FIELD=system_prompt  # Field for system prompt text
DIRECTUS_PROMPTS_MESSAGES_FIELD=messages          # Field for prompt messages

SCHEMA_EXCLUDE_COLLECTIONS

Excludes specific collections from schema loading and all tool operations. Useful for:

• Performance — Skip large log or cache collections
• Security — Prevent AI access to sensitive data
• Focus — Limit the AI to only relevant collections

SCHEMA_EXCLUDE_COLLECTIONS=activity_logs,cache,temp_uploads,user_sessions

ALLOW_SYSTEM_MODIFICATIONS

Controls whether the AI can modify Directus system collections (directus_users, directus_roles, directus_permissions, etc.). Disabled by default.

• false (default) — Blocks create/update on system collections (read is always allowed)
• true — Allows system collection modifications. Use with caution; incorrect changes can break your Directus instance

DISABLE_TOOLS

Comma-separated list of tool names to disable. Default: directus_delete_item.

# Disable all destructive operations
DISABLE_TOOLS=directus_delete_item,directus_delete_flow,directus_delete_operation,directus_delete_relation

DIRECTUS_PROMPTS_COLLECTION_ENABLED

When enabled, exposes the directus_get_prompts tool which reads LLM prompts from a Directus collection. Requires DIRECTUS_PROMPTS_COLLECTION to specify the collection name. The field mapping variables (*_FIELD) let you customize which fields store the prompt name, description, system prompt, and messages.

Local Development

git clone https://github.com/archawat/mcp-directus
cd mcp-directus
pnpm install
pnpm build
pnpm dev

For local MCP client testing, use the local path:

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

Contributing

Please open issues for bugs or suggestions.

License

MIT

Acknowledgments

• Original project by @rijkvanzanten and the Directus team