Installation

The Model Context Protocol (MCP) is a standard for helping AI tools and LLMs talk to applications and services like Directus.

The Directus Content MCP Server is an interface for content editors to build custom pages, write blog posts, update content, organize assets and more inside your Directus project.

This guide will cover how to connect Directus to your AI tools using MCP.

Prerequisites

Before starting, ensure you have:

• Node.js v22.12 or newer installed on your computer
• An existing Directus project with access credentials
• One of the supported MCP clients: Claude Desktop, Cursor, or Raycast

If you don't have an existing Directus project, you can:

• Start a free trial on Directus Cloud
• Create a local instance with npx directus-template-cli@latest init

Get Directus Credentials

You'll need either a static token or your email and password to connect to your Directus instance:

To get a static access token:

1. Log in to your Directus instance.
2. Navigate to the User Directory and select your user profile.
3. Scroll down to the Token field.
4. Generate a token and copy it.
5. Save the user (do not forget this step).

Installation

Claude Desktop

1. Download and install Claude Desktop if you haven't already.
2. Open Claude Desktop and navigate to Settings.
3. Under the Developer tab, click Edit Config to open the configuration file.
4. Add the following configuration:

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

5. Save the configuration file and restart Claude Desktop.
6. When starting a new chat, you should see the Directus MCP server icon available.

Cursor

1. Download and install Cursor if you haven't already.
2. Create a .cursor directory in your project root if it doesn't exist.
3. Create a .cursor/mcp.json file with the following configuration:

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

4. Save the configuration file.
5. Open Cursor and navigate to Settings → MCP to verify the server connection status.

Raycast

1. Download and install Raycast if you haven't already.
2. Open Raycast and search for "MCP Servers".
3. Select "Install Server" from the MCP Servers menu.
4. Copy and paste the following configuration:

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

5. Replace the placeholder values with your Directus URL and token.
6. Press Command+Enter to install the server.
7. After installation, you can use "@directus" to interact with your Directus instance.

For optimal performance in Raycast, add a custom instruction to "Ask Directus" in your Raycast extensions settings: "Make sure you always call the system prompt tool first."

Using Email/Password Authentication

If you prefer using email and password instead of a token, use this configuration format for any of the platforms:

{
    "mcpServers": {
        "directus": {
            "command": "npx",
            "args": ["@directus/content-mcp@latest"],
            "env": {
                "DIRECTUS_URL": "https://your-directus-url.com",
                "DIRECTUS_USER_EMAIL": "user@example.com",
                "DIRECTUS_USER_PASSWORD": "your_password"
            }
        }
    }
}

Advanced Configuration

System Prompt

The MCP server includes a default system prompt that helps guide the LLM's behavior. You can:

• Override it by setting the MCP_SYSTEM_PROMPT variable.
• Disable it by setting MCP_SYSTEM_PROMPT_ENABLED to false.

Example: Advanced Configuration

{
    "mcpServers": {
        "directus": {
            "command": "npx",
            "args": ["@directus/content-mcp@latest"],
            "env": {
                "DIRECTUS_URL": "https://your-directus-instance.com",
                "DIRECTUS_TOKEN": "your_directus_token",
                "DISABLE_TOOLS": ["delete-item", "update-field"],
                "MCP_SYSTEM_PROMPT_ENABLED": "true",
                "MCP_SYSTEM_PROMPT": "You are an assistant specialized in managing content for our marketing website.",
                "DIRECTUS_PROMPTS_COLLECTION_ENABLED": "true",
                "DIRECTUS_PROMPTS_COLLECTION": "ai_prompts",
                "DIRECTUS_PROMPTS_NAME_FIELD": "name",
                "DIRECTUS_PROMPTS_DESCRIPTION_FIELD": "description",
                "DIRECTUS_PROMPTS_SYSTEM_PROMPT_FIELD": "system_prompt",
                "DIRECTUS_PROMPTS_MESSAGES_FIELD": "messages"
            }
        }
    }
}