# 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)
```bash
npm install -g directus-mcp-server
```
### From source
```bash
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
```bash
npm install
```
## Configuration
Create a `.env` file in the root directory with your Directus configuration:
```env
# 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:
```env
# 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:**
```json
{
"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
```bash
npm run build
```
## Usage
### Running the Server
```bash
npm start
```
Or use the built binary:
```bash
node dist/index.js
```
### MCP Client Configuration
Add to your MCP client configuration (e.g., Claude Desktop, Cline):
**Option 1: Using npx (recommended - no installation needed):**
```json
{
"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"
}
}
}
}
```
**Option 2: Using global installation:**
```json
{
"mcpServers": {
"directus": {
"command": "directus-mcp",
"env": {
"DIRECTUS_URL": "https://your-directus-instance.com",
"DIRECTUS_TOKEN": "your_static_token_here",
"MCP_TOOLSETS": "default"
}
}
}
}
```
**Option 3: Using local source:**
```json
{
"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"
}
}
}
}
```
## Available Tools
### Schema Management Tools
#### `list_collections`
List all collections in the Directus instance.
**Parameters**: None
**Example**:
```json
{}
```
#### `get_collection`
Get detailed information about a specific collection.
**Parameters**:
- `collection` (string): Collection name
**Example**:
```json
{
"collection": "articles"
}
```
#### `create_collection`
Create a new collection (database table) with optional fields. This automatically creates a proper database table, not just a folder.
**Parameters**:
- `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
**Example**:
```json
{
"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"}
]
}
}
}
]
}
```
#### `update_collection`
Update collection metadata.
**Parameters**:
- `collection` (string): Collection name
- `meta` (object): Metadata to update
**Example**:
```json
{
"collection": "articles",
"meta": {
"icon": "article",
"note": "Updated description"
}
}
```
#### `delete_collection`
Delete a collection and all its data.
**Parameters**:
- `collection` (string): Collection name
**Example**:
```json
{
"collection": "articles"
}
```
#### `list_fields`
List all fields in a collection.
**Parameters**:
- `collection` (string): Collection name
**Example**:
```json
{
"collection": "articles"
}
```
#### `create_field`
Add a new field to a collection.
**Parameters**:
- `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
**Example**:
```json
{
"collection": "articles",
"field": "author",
"type": "uuid",
"meta": {
"interface": "select-dropdown-m2o",
"required": true,
"special": ["m2o"]
}
}
```
#### `update_field`
Update field properties.
**Parameters**:
- `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
**Example**:
```json
{
"collection": "articles",
"field": "title",
"meta": {
"note": "Article title (required)"
}
}
```
#### `delete_field`
Remove a field from a collection.
**Parameters**:
- `collection` (string): Collection name
- `field` (string): Field name
**Example**:
```json
{
"collection": "articles",
"field": "old_field"
}
```
#### `list_relations`
List all relations in the Directus instance.
**Parameters**: None
**Example**:
```json
{}
```
#### `create_relation`
Create a relation between collections.
**Parameters**:
- `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
**Example (Many-to-One)**:
```json
{
"collection": "articles",
"field": "author",
"related_collection": "users",
"schema": {
"on_delete": "SET NULL"
}
}
```
**Example (One-to-Many)**:
```json
{
"collection": "articles",
"field": "author",
"related_collection": "users",
"meta": {
"one_field": "articles"
}
}
```
#### `delete_relation`
Delete a relation.
**Parameters**:
- `collection` (string): Collection name
- `field` (string): Field name
**Example**:
```json
{
"collection": "articles",
"field": "author"
}
```
### Content Management Tools
#### `query_items`
Query items with filtering, sorting, and pagination.
**Parameters**:
- `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`
**Example**:
```json
{
"collection": "articles",
"filter": {
"status": {"_eq": "published"},
"date_created": {"_gte": "2024-01-01"}
},
"sort": ["-date_created"],
"limit": 10
}
```
#### `get_item`
Get a single item by ID.
**Parameters**:
- `collection` (string): Collection name
- `id` (string|number): Item ID
- `fields` (array, optional): Fields to return
- `deep` (object, optional): Deep relational queries
**Example**:
```json
{
"collection": "articles",
"id": 1,
"fields": ["id", "title", "status", "author.first_name"]
}
```
#### `create_item`
Create a new item.
**Parameters**:
- `collection` (string): Collection name
- `data` (object): Item data
**Example**:
```json
{
"collection": "articles",
"data": {
"title": "My New Article",
"status": "draft",
"body": "Article content here...",
"author": "user-uuid-here"
}
}
```
#### `update_item`
Update an existing item.
**Parameters**:
- `collection` (string): Collection name
- `id` (string|number): Item ID
- `data` (object): Fields to update
**Example**:
```json
{
"collection": "articles",
"id": 1,
"data": {
"status": "published"
}
}
```
#### `delete_item`
Delete an item.
**Parameters**:
- `collection` (string): Collection name
- `id` (string|number): Item ID
**Example**:
```json
{
"collection": "articles",
"id": 1
}
```
#### `bulk_create_items`
Create multiple items at once.
**Parameters**:
- `collection` (string): Collection name
- `items` (array): Array of item data objects
**Example**:
```json
{
"collection": "articles",
"items": [
{"title": "Article 1", "status": "draft"},
{"title": "Article 2", "status": "draft"}
]
}
```
#### `bulk_update_items`
Update multiple items at once.
**Parameters**:
- `collection` (string): Collection name
- `items` (array): Array of items with id and fields to update
**Example**:
```json
{
"collection": "articles",
"items": [
{"id": 1, "status": "published"},
{"id": 2, "status": "published"}
]
}
```
#### `bulk_delete_items`
Delete multiple items at once.
**Parameters**:
- `collection` (string): Collection name
- `ids` (array): Array of item IDs
**Example**:
```json
{
"collection": "articles",
"ids": [1, 2, 3]
}
```
## Common Use Cases
### Setting up a new content model
1. Create a collection with `create_collection`
2. Add fields with `create_field`
3. Create relations with `create_relation`
4. Start adding content with `create_item`
### Querying content with relations
```json
{
"collection": "articles",
"fields": ["*", "author.first_name", "author.last_name"],
"filter": {"status": {"_eq": "published"}},
"sort": ["-date_created"],
"limit": 10
}
```
### Bulk operations
Use `bulk_create_items`, `bulk_update_items`, or `bulk_delete_items` for efficient batch operations.
## Development
```bash
# Watch mode for development
npm run dev
# Build for production
npm run build
```
## Tool Authoring
This project provides utilities to streamline MCP tool development and reduce code duplication:
### Tool Helpers
Use `createTool` for tools that return data, and `createActionTool` for tools that perform actions:
```typescript
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}`
});
```
### Shared Validators
Common Zod schemas are available in `src/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.)
Example usage:
```typescript
import { CollectionNameSchema, ItemIdSchema } from './tools/validators.js';
const MyToolSchema = z.object({
collection: CollectionNameSchema,
id: ItemIdSchema,
// ... other fields
});
```
### Directus Client Resource Factory
The client uses a resource factory pattern for consistent CRUD operations. When adding new Directus resources, define them in the client constructor using `createResourceMethods()`.
## Error Handling
All tools include error handling and will return descriptive error messages for:
- Authentication failures
- Invalid parameters
- API errors
- Network issues
- Validation errors
## License
MIT
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
