Directus MCP Server

@staminna/directus-mcp-server

MCP server for Directus 12 — items, collections, files, flows, users, and schema tools. TypeScript, typed throughout.

Test Coverage

Coverage badges are generated from coverage/coverage-summary.json by npm run badges (no external service required). Run npm run test:coverage first.

Features

• 🔐 Full Authentication - Token-based authentication with Directus
• 📦 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 - User CRUD and role management
• 🔍 Schema Tools - Analyze and validate collection schemas
• 🩺 Diagnostics - Collection access diagnostics and troubleshooting

Installation

Via npm (Recommended)

npm install -g @staminna/directus-mcp-server

From Source

git clone https://github.com/staminna/mcp-server-claude.git

cd mcp-server-claude npm install npm run build

Environment Variables

TLS / client certificates

Set these when the Directus instance uses a private CA or requires a client certificate. Each of CA/CERT/KEY/PFX accepts either a file path or the PEM/DER content itself.

---

Authentication — no OAuth required

This server uses a static Directus access token (DIRECTUS_TOKEN) and runs over stdio transport. OAuth is *not* required, by design:

• The MCP specification only defines OAuth 2.1 authorization for HTTP-based transports. For stdio servers the spec says implementations *"SHOULD NOT"* use it and should instead retrieve credentials from the environment — exactly what this server does.
• Directus 12 fully supports static access tokens. The OAuth 2.1 support Directus added (mid-2026) applies to its own built-in *remote* MCP endpoint and is optional; there are no breaking changes to token authentication in Directus 12 (see DIRECTUS_V12_BREAKING_CHANGES.md).
• OAuth only becomes relevant if you expose an MCP server remotely over HTTP (Streamable HTTP/SSE). As a local stdio subprocess of Claude Desktop, Claude Code, Cursor, etc., this server needs only the env token.

Generate the token in Directus under User Settings → Token (use a dedicated user with least-privilege role for production).

Using with a Claude subscription (Max/Pro) — no API key needed

MCP servers do not consume Anthropic API tokens themselves; only the AI client's model calls do. If you use this server inside Claude Code or Claude Desktop with a Claude Max (or Pro) subscription, the model usage is covered by the subscription — you do not need an Anthropic API key. An API key is only required when driving Claude programmatically via the Claude API (e.g. the remote MCP connector).

---

IDE Configuration

🟣 Cursor

1. Open Cursor Settings: Cmd+, (macOS) or Ctrl+, (Windows/Linux)
2. Search for "MCP" or navigate to Features → MCP Servers
3. Click "Edit in settings.json"
4. Add the following configuration:

{

"mcpServers": { "directus": { "command": "npx", "args": [ "-y", "@staminna/directus-mcp-server" ], "env": { "DIRECTUS_URL": "http://localhost:8065", "DIRECTUS_TOKEN": "your-directus-token-here" } } } }

Or if installed locally:

{

"mcpServers": { "directus": { "command": "node", "args": [ "/path/to/mcp-server-claude/dist/index.js" ], "env": { "DIRECTUS_URL": "http://localhost:8065", "DIRECTUS_TOKEN": "your-directus-token-here" } } } }

1. Save the file and restart Cursor

---

🌊 Windsurf

1. Open Windsurf Settings: Cmd+, (macOS) or Ctrl+, (Windows/Linux)
2. Search for "MCP Servers"
3. Click "Edit in settings.json"
4. Add the following configuration:

{

"mcpServers": { "directus": { "command": "npx", "args": [ "-y", "@staminna/directus-mcp-server" ], "env": { "DIRECTUS_URL": "http://localhost:8065", "DIRECTUS_TOKEN": "your-directus-token-here", "DIRECTUS_PROMPTS_COLLECTION_ENABLED": "true", "DIRECTUS_PROMPTS_COLLECTION": "ai_prompts", "DIRECTUS_RESOURCES_ENABLED": "true", "DIRECTUS_RESOURCES_EXCLUDE_SYSTEM": "true", "NODE_ENV": "production" } } } }

Or if installed locally:

{

"mcpServers": { "directus": { "command": "node", "args": [ "/path/to/mcp-server-claude/dist/index.js" ], "env": { "DIRECTUS_URL": "http://localhost:8065", "DIRECTUS_TOKEN": "your-directus-token-here" } } } }

1. Save the file
2. Quit Windsurf completely (Cmd+Q or Ctrl+Q)
3. Reopen Windsurf and wait ~10 seconds for MCP to initialize

---

🤖 Claude Desktop

1. Locate your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

1. Create or edit the config file:

{

"mcpServers": { "directus": { "command": "npx", "args": [ "-y", "@staminna/directus-mcp-server" ], "env": { "DIRECTUS_URL": "http://localhost:8065", "DIRECTUS_TOKEN": "your-directus-token-here" } } } }

Or if installed locally:

{

"mcpServers": { "directus": { "command": "node", "args": [ "/path/to/mcp-server-claude/dist/index.js" ], "env": { "DIRECTUS_URL": "http://localhost:8065", "DIRECTUS_TOKEN": "your-directus-token-here" } } } }

1. Save the file and restart Claude Desktop

---

🔮 Claude.ai (Web with MCP)

For Claude.ai web interface with MCP support:

1. Navigate to Claude.ai settings
2. Find the MCP configuration section
3. Add a new MCP server with:

{

"name": "directus", "command": "npx", "args": ["-y", "@staminna/directus-mcp-server"], "env": { "DIRECTUS_URL": "http://localhost:8065", "DIRECTUS_TOKEN": "your-directus-token-here" } }

Note: Claude.ai MCP support may require a Pro subscription and specific browser extensions.

---

Available Tools

Collection Management

Schema & Fields

Flow Management

User Management

File Management

Diagnostics