Installation

The local MCP server is a standalone Node.js application that provides an alternative way to connect AI tools to your Directus instance using the Model Context Protocol.

When to Use Local MCP

Consider using the local MCP server if you:

• Need to run MCP in local environments without internet access to your Directus instance
• Prefer Node.js-based tooling and local development workflows
• Want to customize or extend the MCP server functionality
• Are working with older Directus versions that don't support the remote MCP
• Need to run MCP operations through a proxy or custom network setup

Comparison with Remote MCP

This guide will cover how to set up and use the local MCP server as an alternative to the built-in remote option.

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

Choose your AI tool and follow the setup:

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

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

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

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