@staminna/directus-mcp-server

MCP-Server für Directus 12 – Items, Collections, Dateien, Flows, Benutzer und Schema-Tools. TypeScript, durchgängig typisiert.

Testabdeckung

Die Badges zur Testabdeckung werden aus coverage/coverage-summary.json mit npm run badges generiert (kein externer Dienst erforderlich). Führen Sie zuerst npm run test:coverage aus.

Funktionen

• 🔐 Vollständige Authentifizierung – Token-basierte Authentifizierung mit Directus

• 📦 Collection-Verwaltung – CRUD-Operationen für Collections und Items

• 📁 Datei-Operationen – Dateien hochladen, herunterladen und verwalten

• 🔄 Flow-Verwaltung – Directus-Flows erstellen, aktualisieren, auslösen und verwalten

• 👥 Benutzerverwaltung – Benutzer-CRUD und Rollenverwaltung

• 🔍 Schema-Tools – Collection-Schemas analysieren und validieren

• 🩺 Diagnose – Diagnose und Fehlerbehebung beim Collection-Zugriff

Related MCP server: Storyblok MCP Server

Installation

Über npm (empfohlen)

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

Aus dem Quellcode

git clone https://github.com/staminna/mcp-server-claude.git
cd mcp-server-claude
npm install
npm run build

Umgebungsvariablen

TLS / Client-Zertifikate

Setzen Sie diese Werte, wenn die Directus-Instanz eine private CA verwendet oder ein Client-Zertifikat erfordert. Jede der Variablen CA/CERT/KEY/PFX akzeptiert entweder einen Dateipfad oder den PEM/DER-Inhalt selbst.

Authentifizierung – kein OAuth erforderlich

Dieser Server verwendet ein statisches Directus-Zugriffstoken (DIRECTUS_TOKEN) und läuft über stdio-Transport. OAuth ist nicht erforderlich, ganz bewusst:

• Die MCP-Spezifikation definiert OAuth-2.1-Autorisierung nur für HTTP-basierte Transporte. Für stdio-Server besagt die Spezifikation, dass Implementierungen es „SHOULD NOT“ verwenden sollten und stattdessen Anmeldeinformationen aus der Umgebung beziehen sollten – genau das tut dieser Server.

• Directus 12 unterstützt statische Zugriffstokens vollständig. Die OAuth-2.1-Unterstützung, die Directus (Mitte 2026) hinzugefügt hat, gilt für den eigenen integrierten Remote-MCP-Endpunkt und ist optional; es gibt keine Breaking Changes an der Token-Authentifizierung in Directus 12 (siehe DIRECTUS_V12_BREAKING_CHANGES.md).

• OAuth wird nur relevant, wenn Sie einen MCP-Server remote über HTTP bereitstellen (Streamable HTTP/SSE). Als lokaler stdio-Subprozess von Claude Desktop, Claude Code, Cursor usw. benötigt dieser Server nur das Token aus der Umgebung.

Generieren Sie das Token in Directus unter Benutzereinstellungen → Token (verwenden Sie für die Produktion einen dedizierten Benutzer mit einer Rolle mit minimalen Berechtigungen).

Verwendung mit einem Claude-Abonnement (Max/Pro) – kein API-Schlüssel erforderlich

MCP-Server verbrauchen selbst keine Anthropic-API-Tokens; nur die Modellaufrufe des KI-Clients tun das. Wenn Sie diesen Server in Claude Code oder Claude Desktop mit einem Abonnement für Claude Max (oder Pro) verwenden, wird die Modellnutzung durch das Abonnement abgedeckt – Sie benötigen keinen Anthropic-API-Schlüssel. Ein API-Schlüssel ist nur erforderlich, wenn Sie Claude programmatisch über die Claude-API steuern (z. B. über den Remote-MCP-Connector).

IDE-Konfiguration

🟣 Cursor

1. Öffnen Sie die Cursor-Einstellungen: Cmd+, (macOS) oder Ctrl+, (Windows/Linux)

2. Suchen Sie nach „MCP“ oder navigieren Sie zu Features → MCP Servers

3. Klicken Sie auf „Edit in settings.json“

4. Fügen Sie die folgende Konfiguration hinzu:

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

Oder wenn lokal installiert:

{
  "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. Speichern Sie die Datei und starten Sie Cursor neu

🌊 Windsurf

1. Öffnen Sie die Windsurf-Einstellungen: Cmd+, (macOS) oder Ctrl+, (Windows/Linux)

2. Suchen Sie nach „MCP Servers“

3. Klicken Sie auf „Edit in settings.json“

4. Fügen Sie die folgende Konfiguration hinzu:

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

Oder wenn lokal installiert:

{
  "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. Speichern Sie die Datei

6. Beenden Sie Windsurf vollständig (Cmd+Q oder Ctrl+Q)

7. Öffnen Sie Windsurf erneut und warten Sie ~10 Sekunden, bis MCP initialisiert ist

🤖 Claude Desktop

1. Suchen Sie die Konfigurationsdatei von Claude Desktop:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Erstellen oder bearbeiten Sie die Konfigurationsdatei:

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

Oder wenn lokal installiert:

{
  "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. Speichern Sie die Datei und starten Sie Claude Desktop neu

🔮 Claude.ai (Web mit MCP)

Für die Claude.ai-Weboberfläche mit MCP-Unterstützung:

1. Navigieren Sie zu den Claude.ai-Einstellungen

2. Suchen Sie den Abschnitt für die MCP-Konfiguration

3. Fügen Sie einen neuen MCP-Server hinzu mit:

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

Hinweis: Die MCP-Unterstützung von Claude.ai erfordert möglicherweise ein Pro-Abonnement und bestimmte Browsererweiterungen.

Verfügbare Tools

Collection-Verwaltung

Schema & Felder

Flow-Verwaltung

Benutzerverwaltung

Dateiverwaltung

Diagnose

Tool-Suche

Tool-Sicherheitsannotationen

Jedes Tool trägt MCP-Annotationen, damit ein Client vor dem Aufruf Lesevorgänge von Schreibvorgängen unterscheiden kann: 17 sind readOnlyHint: true, 6 sind explizit destructiveHint: false (additiv — erstellt), und 11 sind destructiveHint: true (Löschungen, überschreibende Aktualisierungen, apply_schema, import_data, trigger_flow).

Beachte, dass destructiveHint in der MCP-Spezifikation standardmäßig true ist; deshalb setzen die additiven Tools es auf false, anstatt es wegzulassen.

Elemente sicher löschen

Seit Directus 12.3.0 fällt delete_items nie mehr auf das Löschen aller Elemente zurück:

• ids: [...] löscht diese Elemente.

• query: {...} löscht alles, auf das die Abfrage zutrifft.

• Die Übergabe beider wird abgelehnt.

• Die Übergabe keines von beiden löscht nichts und sendet keine Anfrage.

Um jedes Element in einer Collection zu löschen, fordere es ausdrücklich an:

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

Verwendungsbeispiele

Nach der Konfiguration kannst du über deinen KI-Assistenten mit Directus interagieren:

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

Fehlerbehebung

MCP-Server stellt keine Verbindung her

1. Prüfe, ob Directus läuft: Stelle sicher, dass deine Directus-Instanz unter der konfigurierten URL erreichbar ist

2. Prüfe Token-Berechtigungen: Das API-Token benötigt passende Berechtigungen für die Vorgänge, die du ausführen möchtest

3. Starte die IDE neu: Starte deine IDE nach einer Änderung der MCP-Konfiguration vollständig neu

4. Prüfe die Logs: Suche in der Entwicklerkonsole deiner IDE nach MCP-bezogenen Fehlern

Berechtigungsfehler

Stelle sicher, dass dein Directus-Token über die erforderlichen Berechtigungen verfügt:

• Admin-Token für vollständigen Zugriff

• Oder konfiguriere spezifische Rollenberechtigungen für die Collections, auf die du zugreifen musst

Verbindungszeitüberschreitung

Wenn du eine entfernte Directus-Instanz verwendest:

• Prüfe, ob die URL korrekt und erreichbar ist

• Prüfe Firewall-/Netzwerkeinstellungen

• Stelle sicher, dass CORS auf Directus korrekt konfiguriert ist

Entwicklung

# 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

Testen

Das Projekt umfasst Unit-, Integrations- und End-to-End-Suiten (vitest). Abdeckungsschwellen (95 % Statements/Zeilen/Funktionen/Zweige) werden erzwungen — unter diesen Werten schlägt der Testlauf fehl.

# 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-Überprüfung gegen ein echtes Directus

tests/live/demo.mjs steuert alle 34 Tools über stdio gegen eine echte Instanz. Es liegt bewusst außerhalb von npm test — es benötigt Zugangsdaten und einen erreichbaren Server, ist also ein manuelles Gate und kein CI-Gate.

# 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

Die Zugangsdaten werden aus ENV_FILE gelesen (standardmäßig .env.mdbaudio) und gelangen so nie in die Shell-Historie. Die Ergebnisse werden pro Tool als bestanden / von der Instanz abgelehnt / fehlgeschlagen gemeldet, wodurch "dieser Server ist defekt" von "diese Instanz hat abgelehnt" getrennt bleibt. --apply-schema erstellt im merge-Modus Diffs, was einen strikt additiven Diff ergibt; es kann die Wegwerf-Collection also nur neu erstellen — es kann nichts löschen, was bereits existierte. Die Bereinigung läuft auch dann, wenn eine frühere Phase fehlschlägt.

Die E2E-Suite verwendet den offiziellen MCP-SDK-Client (StdioClientTransport), um dist/index.js als Unterprozess zu starten, der mit einem prozessinternen Mock-Directus auf einem ephemeren Port kommuniziert — es wird weder eine echte Directus-Instanz noch Netzwerkzugriff benötigt.

Mitwirken

Beiträge sind willkommen! Du kannst gerne einen Pull Request einreichen.

1. Forke das Repository

2. Erstelle deinen Feature-Branch (git checkout -b feature/amazing-feature)

3. Committe deine Änderungen (git commit -m 'Add some amazing feature')

4. Pushe den Branch (git push origin feature/amazing-feature)

5. Öffne einen Pull Request

Lizenz

MIT © Jorge Domingues Nunes

Links

• npm-Paket

• GitHub-Repository

• Directus-Dokumentation

• MCP-Protokollspezifikation