Repository avatar
Other Tools
v12.6.0
active

directus-mcp-server

io.github.staminna/directus-mcp-server

MCP server for Directus 12 — items, collections, files, flows, users, and schema tools

Documentation

@staminna/directus-mcp-server

Turn Directus 12 into an AI-operated backend. Your agent models the data, ships the API, imports your records, wires the automations and debugs the permissions. You just describe the business. Reduce costs

npm version License: MIT CI mcp-server-claude MCP server

mcp-server-claude MCP server

Test Coverage

StatementsBranchesFunctionsLines
StatementsBranchesFunctionsLines

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


Why this, why now

Directus already gives you a production backend for free: a SQL database you own, instant REST + GraphQL APIs, auth, roles and permissions, file storage, Flows (automation) and a no-code admin app for your team. What it doesn't give you is speed of setup. Modelling collections, relations, permissions and flows still takes clicks and hours.

This MCP server lets Claude, Cursor or any MCP agent run Directus for you. 34 typed tools cover collections, fields, relations, items, bulk ops, CSV/JSON import, schema snapshot/diff/apply, flows, users, files and access diagnostics. Each one carries read/write safety annotations, and deletes and schema applies require explicit confirmation.

What you can stand up in an afternoon:

  • 🛒 Shop / catalog: products, categories, variants, stock, images; import the supplier CSV; the API is ready for your storefront.
  • 🌐 Website CMS: pages, menus, blog, SEO fields, translations; your marketing team edits in the Directus app.
  • 🤝 Lightweight CRM: leads, companies, deals, activity; a Flow notifies you on every new lead.
  • 📅 Bookings / services: resources, slots, customers, reservations, with roles for staff and the public.
  • 🧰 Internal back-office: replace the spreadsheet; keep the data in SQL with an audit trail and permissions.

Then move it between environments with get_schema_snapshot → diff_schema → apply_schema.


Quick start (60 seconds)

  1. In Directus, create a user for the agent and generate a static token (User → Token).
  2. Paste the config below into your agent.
  3. Ask: "List my collections, then create a products collection with name, price, stock and a many-to-one category."

Requires Node.js ≥ 26 · works with Directus 12.0 – 12.6 (compatibility notes).

Add it to your agent

One config works for every MCP client:

{
  "mcpServers": {
    "directus": {
      "command": "npx",
      "args": ["-y", "@staminna/directus-mcp-server"],
      "env": {
        "DIRECTUS_URL": "https://your-directus.example.com",
        "DIRECTUS_TOKEN": "your-static-token"
      }
    }
  }
}
ClientWhere it goes
Claude Codeclaude mcp add directus -e DIRECTUS_URL=https://… -e DIRECTUS_TOKEN=… -- npx -y @staminna/directus-mcp-server
Claude Desktopclaude_desktop_config.json (Settings → Developer → Edit Config)
Cursor~/.cursor/mcp.json or .cursor/mcp.json in the project
Windsurf~/.codeium/windsurf/mcp_config.json
VS Code / Cline / othersthe client's MCP config, using the same mcpServers block

Restart the client after editing. Other ways to run it:

  • From source: "command": "node", "args": ["/path/to/mcp-server-claude/dist/index.js"] (after npm install && npm run build)
  • Docker: "command": "docker", "args": ["run", "-i", "--rm", "-e", "DIRECTUS_URL", "-e", "DIRECTUS_TOKEN", "directus-mcp"] (after docker build -t directus-mcp .)

Ask for outcomes, not API calls

"Create a products catalog: products (name, slug, price, stock, images) with a M2O category and M2M tags."
"Import customers.csv into the customers collection — dry run first."
"Create a flow that runs when an order is created and posts it to my webhook."
"Why can't the Public role read articles? Diagnose it."
"Snapshot the schema of products and categories so I can apply it to production."
"Show me all orders from this week over 100 €, newest first."

Tools

Collection Management

ToolDescription
list_collectionsList all collections; folders and inactive collections (Directus 12.4) are marked
get_collection_schemaGet schema for a specific collection
get_collection_itemsGet items from a collection with filtering; search also matches related fields on m2m junctions (Directus 12.6.1)
create_collectionCreate a new collection
delete_collectionDelete a collection (requires confirm)
create_itemCreate a new item in a collection
update_itemUpdate an existing item, optionally into a draft version
delete_itemsDelete items by ids or by query (see note below)
bulk_operationsExecute bulk create, update, delete

Schema & Fields

ToolDescription
create_fieldCreate a new field in a collection
update_fieldUpdate an existing field
delete_fieldDelete a field from a collection
create_relationshipCreate relationships (O2O, O2M, M2O, M2M, M2A)
analyze_collection_schemaAnalyze schema with relationship mapping
validate_collection_schemaValidate schema and relationships
analyze_relationshipsAnalyze relationships across collections
get_schema_snapshotRead a full or partial snapshot of the data model
diff_schemaCompare a snapshot against the live schema (merge or mirror). Directus drops request bodies over ~96 KB, so pass a partial snapshot from get_schema_snapshot with include_collections on any sizeable data model — see DIRECTUS_V12_BREAKING_CHANGES.md
apply_schemaApply a diff (requires confirm)

Flow Management

ToolDescription
get_flowsGet all flows, optionally by folder (Directus 12.4)
get_flowGet a specific flow by ID
create_flowCreate a new automation flow, optionally inside a folder
update_flowUpdate an existing flow
delete_flowDelete a flow
trigger_flowManually trigger a flow
get_operationsGet flow operations

User Management

ToolDescription
get_usersGet all users with filtering
get_userGet a specific user by ID

File Management

ToolDescription
get_filesGet files with filtering and pagination
import_dataImport CSV/JSON into one collection, or several at once

Diagnostics

ToolDescription
diagnose_collection_accessDiagnose collection access issues
refresh_collection_cacheRefresh collection cache
validate_collection_creationValidate newly created collections

Discovery

ToolDescription
search_toolsFind the tools matching a task description

Built-in safety

  • Every tool carries MCP annotations: 17 are read-only, 6 are additive (destructiveHint: false), and 11 are destructive (deletes, overwriting updates, apply_schema, import_data, trigger_flow).
  • Deletes and apply_schema require confirm: true. delete_items takes either ids or a query, never falls back to deleting everything, and (since Directus 12.4) only reaches items the token can read. To wipe a collection you must ask explicitly: { "query": { "limit": -1 }, "confirm": true }.

Configuration

Environment variables
VariableRequiredDescription
DIRECTUS_URLYesYour Directus instance URL (e.g., http://localhost:8065)
DIRECTUS_TOKENYesStatic API token with appropriate permissions
DIRECTUS_PROMPTS_COLLECTION_ENABLEDNoEnable AI prompts collection (true/false)
DIRECTUS_PROMPTS_COLLECTIONNoCollection name for AI prompts (default: ai_prompts)
DIRECTUS_RESOURCES_ENABLEDNoEnable resources feature (true/false)
DIRECTUS_RESOURCES_EXCLUDE_SYSTEMNoExclude system collections from resources (true/false)
NODE_ENVNoEnvironment mode (development/production)
DIRECTUS_TIMEOUTNoRequest timeout in ms (default: 30000)
DIRECTUS_RETRIESNoRetry attempts for network errors, 5xx and 429 (default: 3)
DIRECTUS_RETRY_DELAYNoBase backoff delay in ms (default: 1000)
DIRECTUS_MAX_RETRY_DELAYNoBackoff ceiling in ms (default: 10000)
DIRECTUS_IMPORT_MAX_FILE_SIZENoClient-side import size ceiling in bytes, mirroring the Directus IMPORT_MAX_FILE_SIZE (default: 50 MB)
LOG_LEVELNoDEBUG/INFO/WARN/ERROR (default: INFO). Logs go to stderr; stdout is reserved for MCP
TLS / client certificates

For a private CA or a client certificate. CA/CERT/KEY/PFX accept a file path or the PEM/DER content itself.

| Variable | Description | |

Authentication: a static Directus token over stdio. No OAuth is needed: the MCP spec reserves OAuth for HTTP transports and tells stdio servers to read credentials from the environment. Use a dedicated least-privilege user in production. With a Claude Pro/Max subscription in Claude Code or Desktop you don't need an Anthropic API key either.


Troubleshooting

  • Not connecting: check DIRECTUS_URL is reachable and the token is set, then fully restart the client. Logs go to stderr (LOG_LEVEL=DEBUG for more).
  • Permission errors: run diagnose_collection_access on the collection. It tells permissions, inactive collections (12.4+) and folders apart.
  • Timeouts on a remote instance: raise DIRECTUS_TIMEOUT and check firewall/proxy settings.

Development

npm install && npm run build      # build to dist/
npm run typecheck && npm run lint
npm test                          # unit + integration (vitest)
npm run test:coverage             # enforces 95% thresholds
npm run test:e2e                  # spawns the real server over stdio against a mock Directus
npm run badges                    # refresh the coverage badges above
npm run tdqs                      # tool-definition quality gate (no API key needed)

Live verification: tests/live/demo.mjs drives every tool against a real instance. It reads DIRECTUS_URL/DIRECTUS_TOKEN from ENV_FILE (default .env.mdbaudio):

ENV_FILE=.env npm run test:live                               # read-only + guards
ENV_FILE=.env npm run test:live -- --write                    # + scratch mcp_demo_<stamp> collection, always cleaned up
ENV_FILE=.env npm run test:live -- --write --apply-schema     # + apply_schema, merge mode, scratch only

Tool-definition quality: the 34 definitions are held to TDQS, the open rubric Glama scores MCP servers with. A description has to state what the tool does, when to use it instead of its siblings, the side effects and failure modes an agent cannot infer from the schema, and what it returns; every parameter carries a description. npm run tdqs runs the deterministic stages of that check — no model, no API key — and fails on errors; npm run tdqs:report prints the full findings, notes and warnings included. CI runs the gate on every push and pull request.

Contributions welcome: fork, branch, open a PR. Start with CONTRIBUTING.md; vulnerabilities go through SECURITY.md, not a public issue.

License

MIT © Jorge Domingues Nunes

npm · GitHub · Directus docs · MCP spec

NPM
@staminna/directus-mcp-server
Install Command
npm install @staminna/directus-mcp-server