# @staminna/directus-mcp-server
Enhanced MCP (Model Context Protocol) server for Directus with TypeScript, WebSocket support, and full API coverage.
[](https://www.npmjs.com/package/@staminna/directus-mcp-server)
[](https://opensource.org/licenses/MIT)
## 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
- ⚡ **WebSocket Support** - Real-time subscriptions (coming soon)
## Installation
### Via npm (Recommended)
```bash
npm install -g @staminna/directus-mcp-server
```
### From Source
```bash
git clone https://github.com/staminna/mcp-server-claude.git
cd mcp-server-claude
npm install
npm run build
```
## Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `DIRECTUS_URL` | Yes | Your Directus instance URL (e.g., `http://localhost:8065`) |
| `DIRECTUS_TOKEN` | Yes | Static API token with appropriate permissions |
| `DIRECTUS_PROMPTS_COLLECTION_ENABLED` | No | Enable AI prompts collection (`true`/`false`) |
| `DIRECTUS_PROMPTS_COLLECTION` | No | Collection name for AI prompts (default: `ai_prompts`) |
| `DIRECTUS_RESOURCES_ENABLED` | No | Enable resources feature (`true`/`false`) |
| `DIRECTUS_RESOURCES_EXCLUDE_SYSTEM` | No | Exclude system collections from resources (`true`/`false`) |
| `NODE_ENV` | No | Environment mode (`development`/`production`) |
---
## 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:
```json
{
"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:**
```json
{
"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:
```json
{
"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:**
```json
{
"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:
```json
{
"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:**
```json
{
"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:
```json
{
"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
| Tool | Description |
|------|-------------|
| `list_collections` | List all collections in Directus |
| `get_collection_schema` | Get schema for a specific collection |
| `get_collection_items` | Get items from a collection with filtering |
| `create_collection` | Create a new collection |
| `create_item` | Create a new item in a collection |
| `update_item` | Update an existing item |
| `delete_items` | Delete items from a collection |
| `bulk_operations` | Execute bulk create, update, delete |
### Schema & Fields
| Tool | Description |
|------|-------------|
| `create_field` | Create a new field in a collection |
| `update_field` | Update an existing field |
| `delete_field` | Delete a field from a collection |
| `create_relationship` | Create relationships (O2O, O2M, M2O, M2M, M2A) |
| `analyze_collection_schema` | Analyze schema with relationship mapping |
| `validate_collection_schema` | Validate schema and relationships |
| `analyze_relationships` | Analyze relationships across collections |
### Flow Management
| Tool | Description |
|------|-------------|
| `get_flows` | Get all flows with optional filtering |
| `get_flow` | Get a specific flow by ID |
| `create_flow` | Create a new automation flow |
| `update_flow` | Update an existing flow |
| `delete_flow` | Delete a flow |
| `trigger_flow` | Manually trigger a flow |
| `get_operations` | Get flow operations |
### User Management
| Tool | Description |
|------|-------------|
| `get_users` | Get all users with filtering |
| `get_user` | Get a specific user by ID |
### File Management
| Tool | Description |
|------|-------------|
| `get_files` | Get files with filtering and pagination |
### Diagnostics
| Tool | Description |
|------|-------------|
| `diagnose_collection_access` | Diagnose collection access issues |
| `refresh_collection_cache` | Refresh collection cache |
| `validate_collection_creation` | Validate newly created collections |
---
## 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
```bash
# 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
```
---
## 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](https://github.com/staminna)
---
## Links
- [npm Package](https://www.npmjs.com/package/@staminna/directus-mcp-server)
- [GitHub Repository](https://github.com/staminna/mcp-server-claude)
- [Directus Documentation](https://docs.directus.io/)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
