Directus Task MCP Server

A Model Context Protocol (MCP) server for managing tasks in Directus with automatic schema synchronization. This server allows you to interact with your Directus PostgreSQL database through AI assistants like Claude or Cursor.

Features

Task Management: Create, read, update, and delete tasks
Schema Management: Automatically sync TypeScript models to Directus collections
Filtering: Filter tasks by status, priority, and other criteria
Validation: Built-in validation using Zod schemas
Type Safety: Full TypeScript support with proper typing

Prerequisites

Node.js 18+
A Directus instance (local or hosted)
Directus API token or user credentials

Installation

Clone and setup the project:
```
npm install
npm run build
```
Configure your Directus connection:

The server uses the following environment variables:
- DIRECTUS_URL: Your Directus instance URL (default: https://te9-pg-api.up.railway.app/)
- DIRECTUS_TOKEN: Your Directus API token (default: mo7tahjWjKgHW-42_tEMThJiqBstu2V_)
- DIRECTUS_USER_EMAIL: Alternative to token - user email
- DIRECTUS_USER_PASSWORD: Alternative to token - user password

Configuration

For Cursor

Create a .cursor/mcp.json file in your project root:

{
  "mcpServers": {
    "directus-tasks": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "DIRECTUS_URL": "https://te9-pg-api.up.railway.app/",
        "DIRECTUS_TOKEN": "mo7tahjWjKgHW-42_tEMThJiqBstu2V_"
      }
    }
  }
}

For Claude Desktop

Open Claude Desktop settings
Navigate to Developer tab and click "Edit Config"

Add the following configuration:

{
  "mcpServers": {
    "directus-tasks": {
      "command": "node",
      "args": ["/absolute/path/to/your/project/dist/index.js"],
      "env": {
        "DIRECTUS_URL": "https://te9-pg-api.up.railway.app/",
        "DIRECTUS_TOKEN": "mo7tahjWjKgHW-42_tEMThJiqBstu2V_"
      }
    }
  }
}

Important: Replace /absolute/path/to/your/project with the actual absolute path to your project directory.

Available Tools

The MCP server provides the following tools:

Schema Management

sync-task-schema: Synchronizes the Task model schema with your Directus database

Task Management

list-tasks: List all tasks with optional filtering by status, priority, and limit
get-task: Get a specific task by ID
create-task: Create a new task
update-task: Update an existing task
delete-task: Delete a task

User Management

get-user-info: Get current user information

Task Model

The Task model includes the following fields:

interface Task {
  id?: string;              // UUID primary key
  title: string;            // Required task title
  description?: string;     // Optional description
  status: 'todo' | 'in_progress' | 'completed';  // Task status
  priority: 'low' | 'medium' | 'high';           // Task priority
  due_date?: string;        // Optional due date (ISO format)
  created_at?: string;      // Auto-generated creation timestamp
  updated_at?: string;      // Auto-generated update timestamp
  user_created?: string;    // Auto-generated user who created
  user_updated?: string;    // Auto-generated user who updated
}

Usage Examples

1. First Time Setup

Please sync the task schema with the database

2. Create a Task

Create a new task with title "Implement user authentication" and high priority

3. List Tasks

Show me all tasks with status "in_progress"

4. Update a Task

Update task with ID [task-id] to completed status

5. Get Task Details

Show me details for task [task-id]

Development

Project Structure

src/
├── models/
│   └── Task.ts           # Task model with TypeScript interfaces and Zod schemas
├── services/
│   └── SchemaManager.ts  # Schema management service
└── index.ts              # Main MCP server implementation

Adding New Models

Create a new model file in src/models/
Define TypeScript interfaces and Zod schemas
Export field definitions for Directus
Add tools to the main server for the new model
Use SchemaManager to sync the schema

Development Commands

# Install dependencies
npm install

# Build the project
npm run build

# Development mode (watch for changes)
npm run dev

# Start the server directly
npm start

Troubleshooting

Common Issues

Authentication Errors: Verify your Directus URL and token are correct
Schema Sync Failures: Ensure your Directus user has admin permissions
Connection Issues: Check that your Directus instance is accessible

Debugging

The server logs errors to stderr. You can check the logs in your AI assistant's console or terminal.

Security Notes

Store your Directus token securely
Use environment variables for sensitive configuration
Consider using a dedicated service account for the MCP server
Regularly rotate your API tokens

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

MIT License - see LICENSE file for details