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.

::callout{icon="material-symbols:info" color="warning"} Remote vs Local MCP: Directus v11.12+ now includes a built-in remote MCP server that's easier to set up and doesn't require Node.js. We highly recommend using the newer remote MCP server. The local MCP server remains available as an alternative for users who prefer a local setup or need specific Node.js-based functionality. ::

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.

::callout{icon="material-symbols:code" color="info" to="https://github.com/directus/mcp"} View the local Directus Content MCP Server repository on GitHub. ::

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:

::accordion{type="single"}

:::accordion-item{label="Claude Desktop" icon="i-simple-icons-anthropic"}

1. Download Claude Desktop
2. Open Settings → Developer → Edit Config
3. Add this configuration:

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

4. Replace your-directus-url.com with your Directus URL
5. Replace your-directus-token with your user token
6. Restart Claude Desktop

:::

:::accordion-item{label="Cursor" icon="vscode-icons:file-type-cursorrules"}

1. Download Cursor
2. Create .cursor/mcp.json in your project root:

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

3. Replace URLs and tokens
4. Verify connection in Settings → MCP

:::

:::accordion-item{label="Raycast" icon="i-simple-icons-raycast"}

1. Download Raycast
2. Search "MCP Servers" → "Install Server"
3. Paste configuration:

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

4. Press ⌘ + Enter to install
5. Use @directus to interact with your instance

Tip: Add custom instruction: "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": "[email protected]",
				"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"
			}
		}
	}
}