@staminna/directus-mcp-server

Servidor MCP para Directus 12 — elementos, colecciones, archivos, flujos, usuarios y herramientas de esquema. TypeScript, totalmente tipado.

Cobertura de pruebas

Las insignias de cobertura se generan a partir de coverage/coverage-summary.json con npm run badges (no se requiere ningún servicio externo). Ejecuta primero npm run test:coverage.

Características

• 🔐 Autenticación completa - autenticación basada en token con Directus

• 📦 Gestión de colecciones - operaciones CRUD para colecciones y elementos

• 📁 Operaciones de archivos - subir, descargar y gestionar archivos

• 🔄 Gestión de flujos - crear, actualizar, disparar y gestionar Directus Flows

• 👥 Gestión de usuarios - CRUD de usuarios y gestión de roles

• 🔍 Herramientas de esquema - analizar y validar esquemas de colecciones

• 🩺 Diagnósticos - diagnósticos de acceso a colecciones y resolución de problemas

Related MCP server: Storyblok MCP Server

Instalación

Mediante npm (recomendado)

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

Desde el código fuente

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

Variables de entorno

TLS / certificados de cliente

Establece estas variables cuando la instancia de Directus utilice una CA privada o requiera un certificado de cliente. Cada una de CA/CERT/KEY/PFX acepta una ruta de archivo o el contenido PEM/DER directamente.

Autenticación — no se requiere OAuth

Este servidor utiliza un token de acceso estático de Directus (DIRECTUS_TOKEN) y se ejecuta mediante transporte stdio. OAuth no es necesario, por diseño:

• La especificación MCP solo define la autorización OAuth 2.1 para transportes basados en HTTP. Para los servidores stdio, la especificación dice que las implementaciones "SHOULD NOT" (no deben) usarlo y, en su lugar, deben obtener las credenciales del entorno — exactamente lo que hace este servidor.

• Directus 12 es totalmente compatible con los tokens de acceso estáticos. El soporte de OAuth 2.1 que Directus añadió (a mediados de 2026) se aplica a su propio endpoint remoto de MCP integrado y es opcional; no hay cambios que rompan la compatibilidad en la autenticación por token en Directus 12 (consulta DIRECTUS_V12_BREAKING_CHANGES.md).

• OAuth solo cobra relevancia si expones un servidor MCP de forma remota a través de HTTP (Streamable HTTP/SSE). Como subproceso local stdio de Claude Desktop, Claude Code, Cursor, etc., este servidor solo necesita el token del entorno.

Genera el token en Directus en Configuración de usuario → Token (para producción, usa un usuario dedicado con un rol de mínimos privilegios).

Uso con una suscripción de Claude (Max/Pro) — no se necesita clave de API

Los servidores MCP no consumen tokens de la API de Anthropic por sí mismos; solo lo hacen las llamadas al modelo del cliente de IA. Si usas este servidor dentro de Claude Code o Claude Desktop con una suscripción a Claude Max (o Pro), el uso del modelo está cubierto por la suscripción: no necesitas una clave de API de Anthropic. Solo se requiere una clave de API cuando utilices Claude mediante programación a través de la API de Claude (p. ej., el conector MCP remoto).

Configuración de IDE

🟣 Cursor

1. Abre los Ajustes de Cursor: Cmd+, (macOS) o Ctrl+, (Windows/Linux)

2. Busca "MCP" o navega a Funciones → Servidores MCP

3. Haz clic en "Editar en settings.json"

4. Añade la siguiente configuración:

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

O si está instalado localmente:

{
  "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. Guarda el archivo y reinicia Cursor

🌊 Windsurf

1. Abre los Ajustes de Windsurf: Cmd+, (macOS) o Ctrl+, (Windows/Linux)

2. Busca "Servidores MCP"

3. Haz clic en "Editar en settings.json"

4. Añade la siguiente configuración:

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

O si está instalado localmente:

{
  "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. Guarda el archivo

6. Cierra Windsurf por completo (Cmd+Q o Ctrl+Q)

7. Vuelve a abrir Windsurf y espera ~10 segundos para que MCP se inicialice

🤖 Claude Desktop

1. Localiza el archivo de configuración de 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. Crea o edita el archivo de configuración:

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

O si está instalado localmente:

{
  "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. Guarda el archivo y reinicia Claude Desktop

🔮 Claude.ai (Web con MCP)

Para la interfaz web de Claude.ai con soporte MCP:

1. Ve a los ajustes de Claude.ai

2. Localiza la sección de configuración de MCP

3. Añade un nuevo servidor MCP con:

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

Nota: El soporte de MCP en Claude.ai puede requerir una suscripción a Pro y extensiones específicas del navegador.

Herramientas disponibles

Gestión de colecciones

Esquema y campos

Gestión de flujos

Gestión de usuarios

Gestión de archivos

Diagnóstico

Descubrimiento

Anotaciones de seguridad de las herramientas

Cada herramienta lleva anotaciones MCP para que un cliente pueda distinguir las lecturas de las escrituras antes de llamarla: 17 son readOnlyHint: true, 6 son explícitamente destructiveHint: false (aditivas — crean), y 11 son destructiveHint: true (eliminaciones, actualizaciones que sobrescriben, apply_schema, import_data, trigger_flow).

Ten en cuenta que destructiveHint por defecto es true en la especificación MCP, por lo que las herramientas aditivas lo establecen en false en lugar de omitirlo.

Eliminar elementos de forma segura

A partir de Directus 12.3.0, delete_items nunca recurre a eliminarlo todo:

• ids: [...] elimina esos elementos.

• query: {...} elimina todo lo que coincida con la consulta.

• Se rechaza pasar ambos.

• No pasar ninguno no elimina nada y no realiza ninguna solicitud.

Para eliminar todos los elementos de una colección, pídelo explícitamente:

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

Ejemplos de uso

Una vez configurado, puedes interactuar con Directus a través de tu asistente de IA:

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

Solución de problemas

El servidor MCP no se conecta

1. Verifica que Directus esté en ejecución: Asegúrate de que tu instancia de Directus sea accesible en la URL configurada

2. Comprueba los permisos del token: El token de API necesita permisos adecuados para las operaciones que deseas realizar

3. Reinicia el IDE: Después de cambiar la configuración de MCP, reinicia completamente tu IDE

4. Revisa los registros: Busca errores relacionados con MCP en la consola de desarrollador de tu IDE

Errores de permisos

Asegúrate de que tu token de Directus tenga los permisos necesarios:

• Token de administrador para acceso completo

• O configura permisos de rol específicos para las colecciones a las que necesites acceder

Tiempo de espera de conexión

Si usas una instancia remota de Directus:

• Verifica que la URL sea correcta y accesible

• Comprueba la configuración del firewall/red

• Asegúrate de que CORS esté configurado correctamente en Directus

Desarrollo

# 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

Pruebas

El proyecto incluye suites de pruebas unitarias, de integración y de extremo a extremo (vitest). Se aplican umbrales de cobertura (95% de sentencias/líneas/funciones/ramas) — la ejecución de pruebas falla si queda por debajo de ellos.

# 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

Verificación en vivo contra una instancia real de Directus

tests/live/demo.mjs ejecuta las 34 herramientas contra una instancia real a través de stdio. Está deliberadamente fuera de npm test — necesita una credencial y un servidor accesible, por lo que es un control manual en lugar de uno de CI.

# 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

Las credenciales se leen de ENV_FILE (por defecto .env.mdbaudio) para que nunca pasen por el historial del shell. Los resultados se informan por herramienta como pass / refused-by-instance / fail, manteniendo "este servidor está roto" separado de "esta instancia lo rechazó". La opción --apply-schema genera un diff en modo merge, lo que produce un diff estrictamente aditivo, por lo que solo puede volver a crear la colección temporal — no puede eliminar nada que ya existiera. La limpieza se ejecuta incluso si falla una fase anterior.

La suite e2e utiliza el cliente oficial del SDK de MCP (StdioClientTransport) para lanzar dist/index.js como subproceso, comunicándose con un Directus simulado en el mismo proceso en un puerto efímero — no se necesita una instancia real de Directus ni acceso a la red.

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Pull Request.

1. Haz un fork del repositorio

2. Crea tu rama de funcionalidad (git checkout -b feature/amazing-feature)

3. Haz commit de tus cambios (git commit -m 'Add some amazing feature')

4. Haz push a la rama (git push origin feature/amazing-feature)

5. Abre una Pull Request

Licencia

MIT © Jorge Domingues Nunes

Enlaces

• Paquete npm

• Repositorio de GitHub

• Documentación de Directus

• Especificación del protocolo MCP