{
  "markdown": "# @staminna/directus-mcp-server\n\nMCP server for Directus 12 — items, collections, files, flows, users, and schema tools. TypeScript, typed throughout.\n\n[![npm version](https://badge.fury.io/js/%40staminna%2Fdirectus-mcp-server.svg)](https://www.npmjs.com/package/@staminna/directus-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/staminna/mcp-server-claude/actions/workflows/ci.yml/badge.svg)](https://github.com/staminna/mcp-server-claude/actions/workflows/ci.yml)\n[![mcp-server-claude MCP server](https://glama.ai/mcp/servers/staminna/mcp-server-claude/badges/score.svg)](https://glama.ai/mcp/servers/staminna/mcp-server-claude)\n\n[![mcp-server-claude MCP server](https://glama.ai/mcp/servers/staminna/mcp-server-claude/badges/card.svg)](https://glama.ai/mcp/servers/staminna/mcp-server-claude)\n\n### Test Coverage\n\n| Statements | Branches | Functions | Lines |\n|------------|----------|-----------|-------|\n| ![Statements](https://img.shields.io/badge/statements-98.65%25-brightgreen.svg?style=flat) | ![Branches](https://img.shields.io/badge/branches-98.04%25-brightgreen.svg?style=flat) | ![Functions](https://img.shields.io/badge/functions-97.3%25-brightgreen.svg?style=flat) | ![Lines](https://img.shields.io/badge/lines-98.64%25-brightgreen.svg?style=flat) |\n\nCoverage badges are generated from `coverage/coverage-summary.json` by `npm run badges` (no external service required). Run `npm run test:coverage` first.\n\n## Features\n\n- 🔐 **Full Authentication** - Token-based authentication with Directus\n- 📦 **Collection Management** - CRUD operations for collections and items\n- 📁 **File Operations** - Upload, download, and manage files\n- 🔄 **Flow Management** - Create, update, trigger, and manage Directus Flows\n- 👥 **User Management** - User CRUD and role management\n- 🔍 **Schema Tools** - Analyze and validate collection schemas\n- 🩺 **Diagnostics** - Collection access diagnostics and troubleshooting\n\n## Installation\n\n### Via npm (Recommended)\n\n```bash\nnpm install -g @staminna/directus-mcp-server\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/staminna/mcp-server-claude.git\ncd mcp-server-claude\nnpm install\nnpm run build\n```\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `DIRECTUS_URL` | Yes | Your Directus instance URL (e.g., `http://localhost:8065`) |\n| `DIRECTUS_TOKEN` | Yes | Static API token with appropriate permissions |\n| `DIRECTUS_PROMPTS_COLLECTION_ENABLED` | No | Enable AI prompts collection (`true`/`false`) |\n| `DIRECTUS_PROMPTS_COLLECTION` | No | Collection name for AI prompts (default: `ai_prompts`) |\n| `DIRECTUS_RESOURCES_ENABLED` | No | Enable resources feature (`true`/`false`) |\n| `DIRECTUS_RESOURCES_EXCLUDE_SYSTEM` | No | Exclude system collections from resources (`true`/`false`) |\n| `NODE_ENV` | No | Environment mode (`development`/`production`) |\n| `DIRECTUS_TIMEOUT` | No | Request timeout in ms (default: `30000`) |\n| `DIRECTUS_RETRIES` | No | Retry attempts for network errors, 5xx and 429 (default: `3`) |\n| `DIRECTUS_RETRY_DELAY` | No | Base backoff delay in ms (default: `1000`) |\n| `DIRECTUS_MAX_RETRY_DELAY` | No | Backoff ceiling in ms (default: `10000`) |\n| `DIRECTUS_IMPORT_MAX_FILE_SIZE` | No | Client-side import size ceiling in bytes, mirroring the Directus `IMPORT_MAX_FILE_SIZE` (default: 50 MB) |\n| `LOG_LEVEL` | No | `DEBUG`/`INFO`/`WARN`/`ERROR` (default: `INFO`). Logs go to stderr; stdout is reserved for MCP |\n\n### TLS / client certificates\n\nSet these when the Directus instance uses a private CA or requires a client\ncertificate. Each of `CA`/`CERT`/`KEY`/`PFX` accepts either a file path or the\nPEM/DER content itself.\n\n| Variable | Description |\n|----------|-------------|\n| `DIRECTUS_HTTPS_CA` | Certificate authority |\n| `DIRECTUS_HTTPS_CERT` | Client certificate |\n| `DIRECTUS_HTTPS_KEY` | Client private key |\n| `DIRECTUS_HTTPS_PFX` | PKCS#12 bundle (alternative to cert/key) |\n| `DIRECTUS_HTTPS_PASSPHRASE` | Passphrase for the key or PFX |\n| `DIRECTUS_HTTPS_REJECT_UNAUTHORIZED` | `false` to accept self-signed certificates |\n| `DIRECTUS_HTTPS_SERVERNAME` | SNI server name override |\n\n---\n\n## Authentication — no OAuth required\n\nThis server uses a **static Directus access token** (`DIRECTUS_TOKEN`) and runs over **stdio transport**. OAuth is *not* required, by design:\n\n- 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.\n- **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`).\n- 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.\n\nGenerate the token in Directus under **User Settings → Token** (use a dedicated user with least-privilege role for production).\n\n### Using with a Claude subscription (Max/Pro) — no API key needed\n\nMCP 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).\n\n---\n\n## IDE Configuration\n\n### 🟣 Cursor\n\n1. Open Cursor Settings: `Cmd+,` (macOS) or `Ctrl+,` (Windows/Linux)\n2. Search for **\"MCP\"** or navigate to **Features → MCP Servers**\n3. Click **\"Edit in settings.json\"**\n4. Add the following configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"directus\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@staminna/directus-mcp-server\"\n      ],\n      \"env\": {\n        \"DIRECTUS_URL\": \"http://localhost:8065\",\n        \"DIRECTUS_TOKEN\": \"your-directus-token-here\"\n      }\n    }\n  }\n}\n```\n\n**Or if installed locally:**\n\n```json\n{\n  \"mcpServers\": {\n    \"directus\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/path/to/mcp-server-claude/dist/index.js\"\n      ],\n      \"env\": {\n        \"DIRECTUS_URL\": \"http://localhost:8065\",\n        \"DIRECTUS_TOKEN\": \"your-directus-token-here\"\n      }\n    }\n  }\n}\n```\n\n5. Save the file and restart Cursor\n\n---\n\n### 🌊 Windsurf\n\n1. Open Windsurf Settings: `Cmd+,` (macOS) or `Ctrl+,` (Windows/Linux)\n2. Search for **\"MCP Servers\"**\n3. Click **\"Edit in settings.json\"**\n4. Add the following configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"directus\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@staminna/directus-mcp-server\"\n      ],\n      \"env\": {\n        \"DIRECTUS_URL\": \"http://localhost:8065\",\n        \"DIRECTUS_TOKEN\": \"your-directus-token-here\",\n        \"DIRECTUS_PROMPTS_COLLECTION_ENABLED\": \"true\",\n        \"DIRECTUS_PROMPTS_COLLECTION\": \"ai_prompts\",\n        \"DIRECTUS_RESOURCES_ENABLED\": \"true\",\n        \"DIRECTUS_RESOURCES_EXCLUDE_SYSTEM\": \"true\",\n        \"NODE_ENV\": \"production\"\n      }\n    }\n  }\n}\n```\n\n**Or if installed locally:**\n\n```json\n{\n  \"mcpServers\": {\n    \"directus\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/path/to/mcp-server-claude/dist/index.js\"\n      ],\n      \"env\": {\n        \"DIRECTUS_URL\": \"http://localhost:8065\",\n        \"DIRECTUS_TOKEN\": \"your-directus-token-here\"\n      }\n    }\n  }\n}\n```\n\n5. Save the file\n6. **Quit Windsurf completely** (`Cmd+Q` or `Ctrl+Q`)\n7. Reopen Windsurf and wait ~10 seconds for MCP to initialize\n\n---\n\n### 🤖 Claude Desktop\n\n1. Locate your Claude Desktop config file:\n   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n   - **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n2. Create or edit the config file:\n\n```json\n{\n  \"mcpServers\": {\n    \"directus\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@staminna/directus-mcp-server\"\n      ],\n      \"env\": {\n        \"DIRECTUS_URL\": \"http://localhost:8065\",\n        \"DIRECTUS_TOKEN\": \"your-directus-token-here\"\n      }\n    }\n  }\n}\n```\n\n**Or if installed locally:**\n\n```json\n{\n  \"mcpServers\": {\n    \"directus\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/path/to/mcp-server-claude/dist/index.js\"\n      ],\n      \"env\": {\n        \"DIRECTUS_URL\": \"http://localhost:8065\",\n        \"DIRECTUS_TOKEN\": \"your-directus-token-here\"\n      }\n    }\n  }\n}\n```\n\n3. Save the file and restart Claude Desktop\n\n---\n\n### 🔮 Claude.ai (Web with MCP)\n\nFor Claude.ai web interface with MCP support:\n\n1. Navigate to Claude.ai settings\n2. Find the MCP configuration section\n3. Add a new MCP server with:\n\n```json\n{\n  \"name\": \"directus\",\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"@staminna/directus-mcp-server\"],\n  \"env\": {\n    \"DIRECTUS_URL\": \"http://localhost:8065\",\n    \"DIRECTUS_TOKEN\": \"your-directus-token-here\"\n  }\n}\n```\n\n> **Note**: Claude.ai MCP support may require a Pro subscription and specific browser extensions.\n\n---\n\n## Available Tools\n\n### Collection Management\n| Tool | Description |\n|------|-------------|\n| `list_collections` | List all collections in Directus |\n| `get_collection_schema` | Get schema for a specific collection |\n| `get_collection_items` | Get items from a collection with filtering |\n| `create_collection` | Create a new collection |\n| `delete_collection` | Delete a collection (requires `confirm`) |\n| `create_item` | Create a new item in a collection |\n| `update_item` | Update an existing item, optionally into a draft `version` |\n| `delete_items` | Delete items by `ids` or by `query` (see note below) |\n| `bulk_operations` | Execute bulk create, update, delete |\n\n### Schema & Fields\n| Tool | Description |\n|------|-------------|\n| `create_field` | Create a new field in a collection |\n| `update_field` | Update an existing field |\n| `delete_field` | Delete a field from a collection |\n| `create_relationship` | Create relationships (O2O, O2M, M2O, M2M, M2A) |\n| `analyze_collection_schema` | Analyze schema with relationship mapping |\n| `validate_collection_schema` | Validate schema and relationships |\n| `analyze_relationships` | Analyze relationships across collections |\n| `get_schema_snapshot` | Read a full or partial snapshot of the data model |\n| `diff_schema` | Compare 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` |\n| `apply_schema` | Apply a diff (requires `confirm`) |\n\n### Flow Management\n| Tool | Description |\n|------|-------------|\n| `get_flows` | Get all flows with optional filtering |\n| `get_flow` | Get a specific flow by ID |\n| `create_flow` | Create a new automation flow |\n| `update_flow` | Update an existing flow |\n| `delete_flow` | Delete a flow |\n| `trigger_flow` | Manually trigger a flow |\n| `get_operations` | Get flow operations |\n\n### User Management\n| Tool | Description |\n|------|-------------|\n| `get_users` | Get all users with filtering |\n| `get_user` | Get a specific user by ID |\n\n### File Management\n| Tool | Description |\n|------|-------------|\n| `get_files` | Get files with filtering and pagination |\n| `import_data` | Import CSV/JSON into one collection, or several at once |\n\n### Diagnostics\n| Tool | Description |\n|------|-------------|\n| `diagnose_collection_access` | Diagnose collection access issues |\n| `refresh_collection_cache` | Refresh collection cache |\n| `validate_collection_creation` | Validate newly created collections |\n\n### Discovery\n| Tool | Description |\n|------|-------------|\n| `search_tools` | Find the tools matching a task description |\n\n### Tool safety annotations\n\nEvery tool carries MCP annotations so a client can tell reads from writes before\ncalling: 17 are `readOnlyHint: true`, 6 are explicitly `destructiveHint: false`\n(additive — creates), and 11 are `destructiveHint: true` (deletes, overwriting\nupdates, `apply_schema`, `import_data`, `trigger_flow`).\n\nNote that `destructiveHint` **defaults to true** in the MCP spec, which is why\nthe additive tools set it to `false` rather than omitting it.\n\n### Deleting items safely\n\nFollowing Directus 12.3.0, `delete_items` never falls back to deleting\neverything:\n\n- `ids: [...]` deletes those items.\n- `query: {...}` deletes everything the query matches.\n- Passing both is rejected.\n- Passing neither deletes nothing and issues no request.\n\nTo delete every item in a collection, ask for it explicitly:\n\n```json\n{ \"collection\": \"articles\", \"query\": { \"limit\": -1 }, \"confirm\": true }\n```\n\n---\n\n## Usage Examples\n\nOnce configured, you can interact with Directus through your AI assistant:\n\n```\n\"List all collections in my Directus instance\"\n\n\"Create a new collection called 'blog_posts' with title, content, and published fields\"\n\n\"Get all items from the 'products' collection where status is 'published'\"\n\n\"Create a new flow that triggers on item creation in the 'orders' collection\"\n\n\"Analyze the schema of the 'users' collection including relationships\"\n```\n\n---\n\n## Troubleshooting\n\n### MCP Server Not Connecting\n\n1. **Verify Directus is running**: Ensure your Directus instance is accessible at the configured URL\n2. **Check token permissions**: The API token needs appropriate permissions for the operations you want to perform\n3. **Restart IDE**: After changing MCP configuration, fully restart your IDE\n4. **Check logs**: Look for MCP-related errors in your IDE's developer console\n\n### Permission Errors\n\nEnsure your Directus token has the required permissions:\n- Admin token for full access\n- Or configure specific role permissions for collections you need to access\n\n### Connection Timeout\n\nIf using a remote Directus instance:\n- Verify the URL is correct and accessible\n- Check firewall/network settings\n- Ensure CORS is properly configured on Directus\n\n---\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Watch mode\nnpm run dev\n\n# Run server\nnpm start\n\n# Type check\nnpm run typecheck\n\n# Lint\nnpm run lint\n```\n\n### Testing\n\nThe 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.\n\n```bash\n# Unit + integration tests\nnpm test\n\n# With coverage report (coverage/ — text, html, lcov, json-summary)\nnpm run test:coverage\n\n# End-to-end: builds, then spawns the real server over stdio against a mock Directus\nnpm run test:e2e\n\n# Everything\nnpm run test:all\n\n# Refresh the README coverage badges from the last coverage run\nnpm run badges\n```\n\n### Live verification against a real Directus\n\n`tests/live/demo.mjs` drives all 34 tools against a real instance over stdio. It is\ndeliberately outside `npm test` — it needs a credential and a reachable server, so it\nis a manual gate rather than a CI one.\n\n```bash\n# Read-only + guard phases (touches nothing)\nENV_FILE=.env.mdbaudio npm run test:live\n\n# Also create, mutate and drop a scratch mcp_demo_<stamp> collection\nENV_FILE=.env.mdbaudio npm run test:live -- --write\n\n# Additionally exercise apply_schema, confined to that scratch collection\nENV_FILE=.env.mdbaudio npm run test:live -- --write --apply-schema\n```\n\nCredentials are read from `ENV_FILE` (default `.env.mdbaudio`) so they never pass through\nshell history. Results are reported per tool as pass / refused-by-instance / fail, keeping\n\"this server is broken\" separate from \"this instance declined\". `--apply-schema` diffs in\n**merge** mode, which yields a strictly additive diff, so it can only re-create the scratch\ncollection — it cannot drop anything that already existed. Cleanup runs even when an\nearlier phase fails.\n\nThe 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.\n\n---\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n---\n\n## License\n\nMIT © [Jorge Domingues Nunes](https://github.com/staminna)\n\n---\n\n## Links\n\n- [npm Package](https://www.npmjs.com/package/@staminna/directus-mcp-server)\n- [GitHub Repository](https://github.com/staminna/mcp-server-claude)\n- [Directus Documentation](https://docs.directus.io/)\n- [MCP Protocol Specification](https://modelcontextprotocol.io/)\n",
  "bytes": 17014,
  "sha": "52649a9f74aae578d54ce8750137dccee3e7e5f219e6e3a281acfc7249a51077",
  "repo_slug": "staminna/mcp-server-claude",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_staminna_directus_mcp_server_f9a143ea/readme"
}