@staminna/directus-mcp-server

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

Test Coverage

Statements	Branches	Functions	Lines

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

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

5. Save the file
6. Quit Windsurf completely (Cmd+Q or Ctrl+Q)
7. 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

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

3. 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

Discovery

Tool safety annotations

Every tool carries MCP annotations so a client can tell reads from writes before calling: 17 are readOnlyHint: true, 6 are explicitly destructiveHint: false (additive — creates), and 11 are destructiveHint: true (deletes, overwriting updates, apply_schema, import_data, trigger_flow).

Note that destructiveHint defaults to true in the MCP spec, which is why the additive tools set it to false rather than omitting it.

Deleting items safely

Following Directus 12.3.0, delete_items never falls back to deleting everything:

• ids: [...] deletes those items.
• query: {...} deletes everything the query matches.
• Passing both is rejected.
• Passing neither deletes nothing and issues no request.

To delete every item in a collection, ask for it explicitly:

{ "collection": "articles", "query": { "limit": -1 }, "confirm": true }

Since Directus 12.4.0 a query resolves its targets under the token's read permissions: read access to the primary key is required, and only items the token can read are deleted. A token that can delete but not read deletes nothing.

Usage Examples

Once configured, you can interact with Directus through your AI assistant:

"List all collections in my Directus instance"

"Create a new collection called 'blog_posts' with title, content, and published fields"

"Get all items from the 'products' collection where status is 'published'"

"Create a new flow that triggers on item creation in the 'orders' collection"

"Analyze the schema of the 'users' collection including relationships"

Troubleshooting

MCP Server Not Connecting

1. Verify Directus is running: Ensure your Directus instance is accessible at the configured URL
2. Check token permissions: The API token needs appropriate permissions for the operations you want to perform
3. Restart IDE: After changing MCP configuration, fully restart your IDE
4. Check logs: Look for MCP-related errors in your IDE's developer console

Permission Errors

Ensure your Directus token has the required permissions:

• Admin token for full access
• Or configure specific role permissions for collections you need to access

Connection Timeout

If using a remote Directus instance:

• Verify the URL is correct and accessible
• Check firewall/network settings
• Ensure CORS is properly configured on Directus

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run server
npm start

# Type check
npm run typecheck

# Lint
npm run lint

Testing

The project ships unit, integration and end-to-end suites (vitest). Coverage thresholds (95% statements/lines/functions/branches) are enforced — the test run fails below them.

# Unit + integration tests
npm test

# With coverage report (coverage/ — text, html, lcov, json-summary)
npm run test:coverage

# End-to-end: builds, then spawns the real server over stdio against a mock Directus
npm run test:e2e

# Everything
npm run test:all

# Refresh the README coverage badges from the last coverage run
npm run badges

Live verification against a real Directus

tests/live/demo.mjs drives all 34 tools against a real instance over stdio. It is deliberately outside npm test — it needs a credential and a reachable server, so it is a manual gate rather than a CI one.

# Read-only + guard phases (touches nothing)
ENV_FILE=.env.mdbaudio npm run test:live

# Also create, mutate and drop a scratch mcp_demo_<stamp> collection
ENV_FILE=.env.mdbaudio npm run test:live -- --write

# Additionally exercise apply_schema, confined to that scratch collection
ENV_FILE=.env.mdbaudio npm run test:live -- --write --apply-schema

Credentials are read from ENV_FILE (default .env.mdbaudio) so they never pass through shell history. Results are reported per tool as pass / refused-by-instance / fail, keeping "this server is broken" separate from "this instance declined". --apply-schema diffs in merge mode, which yields a strictly additive diff, so it can only re-create the scratch collection — it cannot drop anything that already existed. Cleanup runs even when an earlier phase fails.

The e2e suite uses the official MCP SDK client (StdioClientTransport) to spawn dist/index.js as a subprocess, talking to an in-process mock Directus on an ephemeral port — no real Directus instance or network access needed.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT © Jorge Domingues Nunes

Links

• npm Package
• GitHub Repository
• Directus Documentation
• MCP Protocol Specification