Directus

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.

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

- 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/sdkfor reliable API interactions
- Flexible Authentication: Supports both static tokens and email/password authentication

Create a.envfile 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

-

Static Token(Recommended for production):

- Generate a static token in Directus Admin App
- SetDIRECTUS_TOKENenvironment variable

- Use for development or when static tokens aren't available
- SetDIRECTUS_EMAILandDIRECTUS_PASSWORDenvironment variables

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.

- 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:WhenMCP_TOOLSETSis not set or empty, only tools in thedefaulttoolset are exposed. Thedefaulttoolset contains collections, fields, relations, and content tools, butnotschema, flow, or dashboard tools. Schema, flow, and dashboard tools must be explicitly requested by includingschema,flow, ordashboardsin theMCP_TOOLSETSenvironment variable.

Configuration:Set theMCP_TOOLSETSenvironment 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

{ "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" } } } }

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

Add to your MCP client configuration (e.g., Claude Desktop, Cline):

Option 1: Using npx (recommended - no installation needed):

{ "mcpServers": { "directus": { "command": "npx", "args": ["-y", "directus-mcp-server"], "env": { "DIRECTUS_URL": "https://your-directus-instance.com", "DIRECTUS_TOKEN": "your_static_token_here", "MCP_TOOLSETS": "default" } } } }

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

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

List all collections in the Directus instance.

Get detailed information about a specific collection.

{ "collection": "articles" }

Create a new collection (database table) with optional fields. This automatically creates a proper database table, not just a folder.

- collection(string): Collection name
- meta(object, optional): Collection metadata (icon, note, singleton, etc.)
- schema(object, optional): Database schema configuration (automatically set if not provided)
- fields(array, optional): Initial fields to create

{ "collection": "articles", "meta": { "icon": "article", "note": "Blog articles collection" }, "fields": [ { "field": "id", "type": "integer", "schema": { "is_primary_key": true, "has_auto_increment": true } }, { "field": "title", "type": "string", "meta": { "required": true } }, { "field": "status", "type": "string", "meta": { "interface": "select-dropdown", "options": { "choices": [ {"text": "Draft", "value": "draft"}, {"text": "Published", "value": "published"} ] } } } ] }

- collection(string): Collection name
- meta(object): Metadata to update

{ "collection": "articles", "meta": { "icon": "article", "note": "Updated description" } }

{ "collection": "articles" }

{ "collection": "articles" }

- collection(string): Collection name
- field(string): Field name
- type(string): Field type (string, integer, text, boolean, json, uuid, timestamp, etc.)
- meta(object, optional): Field metadata
- schema(object, optional): Database schema configuration

{ "collection": "articles", "field": "author", "type": "uuid", "meta": { "interface": "select-dropdown-m2o", "required": true, "special": ["m2o"] } }

- collection(string): Collection name
- field(string): Field name
- type(string, optional): Field type
- meta(object, optional): Metadata to update
- schema(object, optional): Schema to update

{ "collection": "articles", "field": "title", "meta": { "note": "Article title (required)" } }

- collection(string): Collection name
- field(string): Field name

{ "collection": "articles", "field": "old_field" }

List all relations in the Directus instance.

- collection(string): Many collection (with foreign key)
- field(string): Field name in many collection
- related_collection(string, optional): One collection
- meta(object, optional): Relation metadata
- schema(object, optional): Database relation configuration

{ "collection": "articles", "field": "author", "related_collection": "users", "schema": { "on_delete": "SET NULL" } }

{ "collection": "articles", "field": "author", "related_collection": "users", "meta": { "one_field": "articles" } }

- collection(string): Collection name
- field(string): Field name

{ "collection": "articles", "field": "author" }

Query items with filtering, sorting, and pagination.

- collection(string): Collection name
- fields(array, optional): Fields to return
- filter(object, optional): Filter criteria
- search(string, optional): Search query
- sort(array, optional): Sort fields (prefix with-for descending)
- limit(number, optional): Maximum items to return
- offset(number, optional): Items to skip
- page(number, optional): Page number
- aggregate(object, optional): Aggregation functions
- groupBy(array, optional): Group by fields
- deep(object, optional): Deep relational queries

Filter Operators:_eq,_neq,_lt,_lte,_gt,_gte,_in,_nin,_null,_nnull,_contains,_ncontains,_starts_with,_nstarts_with,_ends_with,_nends_with,_between,_nbetween

{ "collection": "articles", "filter": { "status": {"_eq": "published"}, "date_created": {"_gte": "2024-01-01"} }, "sort": ["-date_created"], "limit": 10 }

- collection(string): Collection name
- id(string|number): Item ID
- fields(array, optional): Fields to return
- deep(object, optional): Deep relational queries

{ "collection": "articles", "id": 1, "fields": ["id", "title", "status", "author.first_name"] }

- collection(string): Collection name
- data(object): Item data

{ "collection": "articles", "data": { "title": "My New Article", "status": "draft", "body": "Article content here...", "author": "user-uuid-here" } }

- collection(string): Collection name
- id(string|number): Item ID
- data(object): Fields to update

{ "collection": "articles", "id": 1, "data": { "status": "published" } }

- collection(string): Collection name
- id(string|number): Item ID

{ "collection": "articles", "id": 1 }

- collection(string): Collection name
- items(array): Array of item data objects

{ "collection": "articles", "items": [ {"title": "Article 1", "status": "draft"}, {"title": "Article 2", "status": "draft"} ] }

- collection(string): Collection name
- items(array): Array of items with id and fields to update

{ "collection": "articles", "items": [ {"id": 1, "status": "published"}, {"id": 2, "status": "published"} ] }

- collection(string): Collection name
- ids(array): Array of item IDs

{ "collection": "articles", "ids": [1, 2, 3] }

- Create a collection withcreate_collection
- Add fields withcreate_field
- Create relations withcreate_relation
- Start adding content withcreate_item

{ "collection": "articles", "fields": ["*", "author.first_name", "author.last_name"], "filter": {"status": {"_eq": "published"}}, "sort": ["-date_created"], "limit": 10 }

Usebulk_create_items,bulk_update_items, orbulk_delete_itemsfor efficient batch operations.

# Watch mode for development npm run dev # Build for production npm run build

This project provides utilities to streamline MCP tool development and reduce code duplication:

UsecreateToolfor tools that return data, andcreateActionToolfor tools that perform actions:

import { createTool, createActionTool } from './tools/tool-helpers.js'; // Data-returning tool const myTool = createTool({ name: 'my_tool', description: 'Description of what the tool does', inputSchema: MySchema, toolsets: ['default', 'my-category'], handler: async (client, args) => client.someMethod(args) }); // Action tool (returns success message) const myActionTool = createActionTool({ name: 'delete_something', description: 'Delete something', inputSchema: DeleteSchema, toolsets: ['default'], handler: async (client, args) => client.deleteMethod(args.id), successMessage: (args) => Successfully deleted item ${args.id} });

Common Zod schemas are available insrc/tools/validators.ts:

- CollectionNameSchema- For collection names
- ItemIdSchema- For item IDs (string | number)
- FieldsSchema- For field arrays
- FilterSchema- For Directus filter objects
- Query parameter schemas (SortSchema,LimitSchema, etc.)
- Flow-related schemas (FlowTriggerSchema,FlowStatusSchema, etc.)

import { CollectionNameSchema, ItemIdSchema } from './tools/validators.js'; const MyToolSchema = z.object({ collection: CollectionNameSchema, id: ItemIdSchema, // ... other fields });

The client uses a resource factory pattern for consistent CRUD operations. When adding new Directus resources, define them in the client constructor usingcreateResourceMethods().

All tools include error handling and will return descriptive error messages for:

- Authentication failures
- Invalid parameters
- API errors
- Network issues
- Validation errors

Contributions are welcome! Please feel free to submit a Pull Request.

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

Hosted MCP server and coordination layer for AI coding agents — live API contracts, database schema, frontend/backend mismatch detection, and shared handoff tickets for Claude Code, Cursor, Codex, and Lovable.

An MCP server for the Frappe Framework, enabling AI assistants to interact with Frappe's REST API for document management and schema operations.

The MCP server for Bitrix24 provides AI assistants with structured access to the Bitrix24 API. It delivers up-to-date method descriptions, parameters, and valid values, allowing assistants to work with precise data instead of guesswork. This reduces code errors and accelerates Bitrix24 integration development.

One remote MCP server for 500+ production APIs — Stripe, HubSpot, Postgres, Gmail, and more. OAuth and API key auth, credential management, and a CLI.