Directus MCP Server

How to use

Use the MCP server to interact with your Directus instance from your AI editor or assistant. You will configure a local or remote MCP client to run the Directus MCP server, passing either an access token or email/password for authentication. Once configured, you can perform typical Directus operations such as fetching collections and items, uploading files, managing users and roles, and querying system information, all through your MCP-enabled editor.

How to install

Prerequisites you need before installation are Node.js, NPM, and a Directus instance.

Step-by-step commands to prepare and run the Directus MCP server in an MCP client configuration are shown below. Use the inline commands exactly as written.

Install or run the MCP server from your editor configuration by using a standard npx-based flow. The following example configures the MCP server with Directus credentials and points to your Directus instance:

{
  "mcpServers": {
    "directus": {
      "command": "npx",
      "args": ["-y", "@pixelsock/directus-mcp@latest"],
      "env": {
        "DIRECTUS_URL": "https://your-directus-instance.com",
        "DIRECTUS_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Alternative credentials using email and password can also be used. Configure your MCP client with the email and password credentials instead of the access token.

{
  "mcpServers": {
    "directus": {
      "command": "npx",
      "args": ["-y", "@pixelsock/directus-mcp@latest"],
      "env": {
        "DIRECTUS_URL": "https://your-directus-instance.com",
        "DIRECTUS_EMAIL": "[email protected]",
        "DIRECTUS_PASSWORD": "your-password"
      }
    }
  }
}

Additional setup for clients

If you are using Cursor or Claude Desktop as your editor, follow these steps to add and reuse the configuration.

For Cursor, go to Settings → Cursor Settings → MCP, add a new global MCP server, paste the configuration, replace placeholders with your Directus credentials, then save and restart Cursor.

For Claude Desktop, open Settings → Developer, click Edit Config, edit claude_desktop_config.json with your credentials, then save and restart Claude.

Troubleshooting

If you encounter issues starting the MCP server in your editor, verify that your Directus URL is reachable and that your credentials are valid. Then re-save the configuration and restart the MCP client.

Ensure Node.js and NPM are installed on your system. Verify the versions with these commands:

node -v
npm -v

If you run into caching or dependency problems, try clearing the NPM cache and retrying the MCP server start.

Security notes

Keep your Directus credentials secure. Do not commit tokens or passwords in configuration files that are publicly accessible. Prefer using environment variables or secret management where possible.

Supported operations and endpoints

This MCP server exposes a range of Directus operations such as getting collections and items, creating and updating items, uploading files, managing users and roles, and fetching system information. Use these capabilities through your MCP client to build AI-assisted workflows with Directus data.

getItems

Fetch items from a Directus collection using MCP actions.

getItem

Fetch a single item by ID from a Directus collection.

createItem

Create a new item in a Directus collection.

updateItem

Update an existing item in a Directus collection.

deleteItem

Delete an item from a Directus collection.

getCollections

Retrieve all collection schemas from Directus.

getFields

Fetch field definitions for a Directus collection.

getRelations

Retrieve relationship mappings for a Directus collection.

getFiles

List files stored in Directus.

uploadFile

Upload a new file to Directus.

login

Obtain an access token by logging in to Directus.

getUsers

Retrieve user accounts from Directus.

getCurrentUser

Fetch information about the currently authenticated user.

getRoles

List roles defined in Directus for access control.

getPermissions

Fetch permissions configured in Directus.

getSystemInfo

Get system information from the Directus instance.

getActivity

Retrieve activity logs from Directus.

getConfig

Obtain current Directus configuration information.