mcp-server-claude

Purpose

This server is a Model Context Protocol (MCP) server for Directus v12, used to expose the various management capabilities of the Directus headless CMS to AI assistants (such as Claude), enabling AI clients to read and write items in Directus, manage collections and fields, upload files, trigger flows, manage users, and inspect data structures. The project is written in TypeScript and uses type definitions throughout.

Main Capabilities

According to the official description, it provides the following tools and capabilities:

Full Authentication: Token-based Directus authentication.
Collection Management: CRUD operations for collections and items.
File Operations: Upload, download, and manage files.
Flow Management: Create, update, trigger, and manage Directus Flows.
User Management: CRUD and role management for users.
Schema Tools: Analyze and validate collection schemas.
Diagnostics: Collection access diagnostics and troubleshooting.

Tool Safety Annotations

Each tool carries MCP annotations, allowing clients to distinguish read from write operations before invocation: 17 of them are readOnlyHint: true, 6 explicitly set destructiveHint: false(incremental operations are creation-type operations), 11 are destructiveHint: true(deletion, overwrite-style updates,apply_schema、import_data、trigger_flow). The description states that in the MCP specification, destructiveHint defaults to true, so incremental-type tools need to explicitly set it to false rather than omitting the field.

Usage

Installation

Installation via npm is recommended. Environment variables need to be set during configuration. If the Directus instance uses a private CA or requires client certificates, TLS / client certificate related variables can be set:CA、CERT、KEY、PFX each accepts a file path or the PEM/DER content itself.

The server uses a static Directus access token (DIRECTUS_TOKEN) and runs over stdio transport, and by design does not require OAuth: the MCP specification defines OAuth 2.1 authorization only for HTTP-based transports; for stdio servers, the specification recommends that implementations "SHOULD NOT" use it, and should instead obtain credentials from the environment, which is exactly what this server does. Directus 12 fully supports static access tokens. Tokens can be generated in Directus under User Settings → Token, and in production it is recommended to use a dedicated user with a least-privilege role.

Using with a Claude Subscription (Max/Pro)

The MCP server itself does not consume Anthropic API tokens; only the AI client's model calls do. When using Claude Code or Claude Desktop with a Claude Max (or Pro) subscription, model usage is covered by the subscription and no Anthropic API key is required. An API key is only needed when driving Claude programmatically through the Claude API (for example, a remote MCP connector).

Client Configuration

Cursor: Open Cursor settings (on macOS, Cmd+,, on Windows/Linux, Ctrl+,), search for "MCP" or go to Features → MCP Servers, click "Edit in settings.json", add the configuration, then save and restart Cursor.
Windsurf: Open settings (Cmd+, / Ctrl+,), search for "MCP Servers", fully quit Windsurf (Cmd+Q / Ctrl+Q), reopen it and wait about 10 seconds for MCP to initialize.
Claude Desktop: The configuration file location is macOS ~/Library/Application Support/Claude/claude_desktop_config.json，Windows %APPDATA%\Claude\claude_desktop_config.json，Linux ~/.config/Claude/claude_desktop_config.json; After creating or editing this configuration file, restart Claude Desktop.
Claude.ai (Web with MCP): Go to Claude.ai settings, find the MCP configuration section, and add a new MCP server. The description mentions that MCP support for Claude.ai may require a Pro subscription and a specific browser extension.

Safely Deleting Entries

As of Directus 12.3.0,delete_items does not fall back to deleting everything:

ids: [...] Delete the specified entry.
query: {...} Delete all entries matched by the query.
Passing both at the same time will be rejected.
If neither is passed, nothing is deleted and no request is made.

To delete all entries in a collection, it must be explicitly requested. As of Directus 12.4.0, the query resolves targets under the token's read permissions: read permission on the primary key is required, and only entries the token can read are deleted; a token that can delete but cannot read will not delete anything.

Use Cases

Once configured, users can interact with Directus through an AI assistant, for example: reading or writing content entries, creating collections and fields, uploading files, triggering flows, managing users and roles, and analyzing collection schemas. It is suitable for development and content management scenarios that require an AI assistant to directly operate the Directus headless CMS.

Limitations and Notes

Connection troubleshooting: Confirm that Directus is running at the configured URL; check whether the token permissions cover the required operations; fully restart the IDE after changing the MCP configuration; check MCP-related errors in the IDE developer console.
Permission errors: Ensure the Directus token has the required permissions—an admin token has full access, or configure specific role permissions for the collections that need to be accessed.
Connection timeout: If using a remote Directus instance, verify that the URL is correct and accessible, check firewall/network settings, and ensure that CORS is correctly configured on Directus.
The project includes unit, integration, and end-to-end test suites (vitest), and enforces coverage thresholds (95% for statements/lines/functions/branches); if below the threshold, the test run fails; there is also a manual verification script for real instances tests/live/demo.mjs, which is not part of the npm test scope.

Other Information

The project uses the MIT license, and the author is Jorge Domingues Nunes. The official materials do not provide specific pricing or fee information.