anthrop.works Directus MCP Server

A token-efficient Model Context Protocol (MCP) server for Directus CMS, enabling LLMs to interact with Directus instances through optimized tools.

Repository: https://github.com/informatikTirol/anthrop.api_mcp (private) Package: https://www.npmjs.com/package/@informatiktirol/anthrop-api-mcp (public)

Features

• Token-Efficient by Design - Configurable schema limits (default: unlimited) to minimize token usage
• Lazy Schema Loading - Schema fetched on-demand, not at startup
• Granular Access - Query single collections or full schema as needed
• Safe Field Management - Create/update fields with automatic interface defaults
• Multiple Auth Methods - Token or email/password authentication

Installation

The package is publicly available on npm - no authentication required.

Claude Code (CLI)

claude mcp add directus \
  -e DIRECTUS_URL=https://your-directus-instance.com \
  -e DIRECTUS_TOKEN=your-api-token \
  -- npx -y @informatiktirol/anthrop-api-mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
	"mcpServers": {
		"directus": {
			"command": "npx",
			"args": ["-y", "@informatiktirol/anthrop-api-mcp"],
			"env": {
				"DIRECTUS_URL": "https://your-directus-instance.com",
				"DIRECTUS_TOKEN": "your-api-token"
			}
		}
	}
}

Note: For pinned versions, use @informatiktirol/[email protected]

Complete Configuration Reference

Below is a complete claude mcp add command with ALL available parameters and their default values:

claude mcp add directus \
  -e DIRECTUS_URL=https://your-directus-instance.com \
  -e DIRECTUS_TOKEN=your-api-token \
  \
  # Authentication (alternative to token)
  # -e [email protected] \
  # -e DIRECTUS_USER_PASSWORD=your-password \
  \
  # Security
  -e READ_ONLY=true \
  -e DISABLE_TOOLS=delete-item \
  \
  # Optional Tool Groups (default: false)
  -e ENABLE_USER_TOOLS=false \
  -e ENABLE_FILE_TOOLS=false \
  -e ENABLE_COMMENT_TOOLS=false \
  -e ENABLE_FLOW_TOOLS=false \
  -e ENABLE_MARKDOWN_TOOL=false \
  -e ENABLE_ALL_TOOLS=false \
  \
  # Schema Limits (default: unlimited)
  # -e MAX_SCHEMA_COLLECTIONS=10 \
  # -e MAX_SCHEMA_FIELDS_PER_COLLECTION=20 \
  # -e SCHEMA_EXCLUDE_COLLECTIONS=collection1,collection2 \
  \
  # System Prompt
  -e MCP_SYSTEM_PROMPT_ENABLED=true \
  \
  # Prompts Collection (optional)
  -e DIRECTUS_PROMPTS_COLLECTION_ENABLED=false \
  # -e DIRECTUS_PROMPTS_COLLECTION=ai_prompts \
  # -e DIRECTUS_PROMPTS_NAME_FIELD=name \
  # -e DIRECTUS_PROMPTS_DESCRIPTION_FIELD=description \
  # -e DIRECTUS_PROMPTS_SYSTEM_PROMPT_FIELD=system_prompt \
  # -e DIRECTUS_PROMPTS_MESSAGES_FIELD=messages \
  \
  -- npx -y @informatiktirol/anthrop-api-mcp

Note: Parameters prefixed with # are commented out to show optional settings. Remove # to activate.

Authentication Options

Option 1: Static Token (Recommended)

DIRECTUS_URL=https://your-instance.com
DIRECTUS_TOKEN=your-static-token

Option 2: Email/Password

DIRECTUS_URL=https://your-instance.com
[email protected]
DIRECTUS_USER_PASSWORD=your-password

Configuration

Schema Limits (Token Efficiency)

Control how much schema data is loaded:

| Variable | Default | Description | | ---------------------------------- | ----------- | ------------------------------------------------ | | MAX_SCHEMA_COLLECTIONS | unlimited | Max collections in schema (unlimited if not set) | | MAX_SCHEMA_FIELDS_PER_COLLECTION | unlimited | Max fields per collection (unlimited if not set) | | SCHEMA_EXCLUDE_COLLECTIONS | None | Comma-separated list of collections to skip |

Example: Limit Schema for Token Efficiency

claude mcp add directus \
  -e DIRECTUS_URL=https://your-instance.com \
  -e DIRECTUS_TOKEN=your-token \
  -e MAX_SCHEMA_COLLECTIONS=10 \
  -e MAX_SCHEMA_FIELDS_PER_COLLECTION=20 \
  -- npx -y @informatiktirol/anthrop-api-mcp

Token Usage:

• Unlimited (default): Schema size depends on your Directus instance (can be 18,000-20,000+ tokens)
• Limited (e.g., 10 collections, 20 fields): ~500-2,000 tokens per schema call

Security Options

Read-Only Mode

By default, the server runs in read-only mode for maximum safety. All write operations are disabled unless explicitly enabled:

# Default: Read-only mode (write operations disabled)
READ_ONLY=true

# Enable write operations (must be explicitly set)
READ_ONLY=false

Write operations blocked in read-only mode:

Core write operations (always registered):

• create-item, update-item, delete-item
• create-field, update-field

Optional write operations (requires ENABLE_*_TOOLS):

• update-files, import-file (requires ENABLE_FILE_TOOLS=true)
• trigger-flow (requires ENABLE_FLOW_TOOLS=true)
• upsert-comment (requires ENABLE_COMMENT_TOOLS=true)

Example: Enable write access

claude mcp add directus \
  -e DIRECTUS_URL=https://your-instance.com \
  -e DIRECTUS_TOKEN=your-token \
  -e READ_ONLY=false \
  -- npx -y @informatiktirol/anthrop-api-mcp

Optional Tool Groups

The server supports additional tools that are disabled by default for security and token efficiency. Enable them as needed:

| Variable | Default | Tools Enabled | Write Operations | | ------------------------ | ------- | ------------------------------------------------------------------ | -------------------------- | | ENABLE_USER_TOOLS | false | read-users | None (read-only) | | ENABLE_FILE_TOOLS | false | read-files, read-folders, update-files, import-file | Requires READ_ONLY=false | | ENABLE_COMMENT_TOOLS | false | read-comments, upsert-comment | Requires READ_ONLY=false | | ENABLE_FLOW_TOOLS | false | read-flows, trigger-flow | *Requires READ_ONLY=false | | ENABLE_MARKDOWN_TOOL | false | markdown-tool | None (utility) | | ENABLE_ALL_TOOLS | false | All optional tools above (excludes schema management) | Respects READ_ONLY | | ENABLE_SCHEMA_MANAGEMENT | false | schema-snapshot, schema-diff, schema-apply, add-unique-constraint | Requires READ_ONLY=false, must be explicitly enabled |

Important:

• READ_ONLY=true always blocks write operations, even if tool groups are enabled
• Tools marked with * are write operations and require READ_ONLY=false
• Schema management tools are intentionally excluded from ENABLE_ALL_TOOLS - they must be explicitly enabled via ENABLE_SCHEMA_MANAGEMENT=true due to their destructive nature

Example: Enable all tools in read-only mode

claude mcp add directus \
  -e DIRECTUS_URL=https://your-instance.com \
  -e DIRECTUS_TOKEN=your-token \
  -e READ_ONLY=true \
  -e ENABLE_ALL_TOOLS=true \
  -- npx -y @informatiktirol/anthrop-api-mcp

This enables all read tools (read-users, read-files, read-comments, read-flows, markdown-tool) but blocks all write operations.

Example: Enable file tools with write access

claude mcp add directus \
  -e DIRECTUS_URL=https://your-instance.com \
  -e DIRECTUS_TOKEN=your-token \
  -e READ_ONLY=false \
  -e ENABLE_FILE_TOOLS=true \
  -- npx -y @informatiktirol/anthrop-api-mcp

Other Options

# Read-only mode (default: true)
READ_ONLY=false

# Disable specific tools (comma-separated)
DISABLE_TOOLS=delete-item,update-field

# System prompt
MCP_SYSTEM_PROMPT_ENABLED=true
MCP_SYSTEM_PROMPT="Your custom prompt"

# Prompts collection (optional)
DIRECTUS_PROMPTS_COLLECTION_ENABLED=true
DIRECTUS_PROMPTS_COLLECTION=ai_prompts

Available Tools

Core Tools (Always Available)

Discovery & Efficiency:

• help-token-efficient - Token efficiency guide and best practices
• list-collections - Get collection names only (~50 tokens)
• count-items - Count items without fetching data (~20 tokens)
• get-item-summary - Get essential fields only (~200-500 tokens)

Schema:

• read-collection-schema - Get detailed schema for a specific collection
• read-collections - Get schema for multiple collections (respects MAX_SCHEMA_* limits)
• read-fields - Retrieve field definitions for all/specific collections
• read-field - Retrieve definition of a specific field

Data Operations:

• read-items - Fetch items from any collection (default limit: 5, configurable)
• create-item - Create new items (requires READ_ONLY=false)
• update-item - Update existing items (requires READ_ONLY=false)
• delete-item - Delete items (requires READ_ONLY=false, disabled by default via DISABLE_TOOLS)

Field Management:

• create-field - Create fields with safe defaults (requires READ_ONLY=false)
• update-field - Modify existing fields (requires READ_ONLY=false)

User:

• users-me - Get current user info (requires fields parameter)

Optional Tools (Disabled by Default)

Enable via environment variables. See Optional Tool Groups for details.

User Management (ENABLE_USER_TOOLS=true)

• read-users - Read user information with query parameters

File & Folder Management (ENABLE_FILE_TOOLS=true)

• read-files - Read file metadata, optionally get raw content (Base64)
• read-folders - Read folder metadata
• update-files - Update file metadata (requires READ_ONLY=false)
• import-file - Import file from URL (requires READ_ONLY=false)

Comment System (ENABLE_COMMENT_TOOLS=true)

• read-comments - Fetch comments for collection items
• upsert-comment - Create/update comments (requires READ_ONLY=false)

Flow Automation (ENABLE_FLOW_TOOLS=true)

• read-flows - List manually triggerable flows
• trigger-flow - Execute a flow by ID (requires READ_ONLY=false)

Markdown Conversion (ENABLE_MARKDOWN_TOOL=true)

• markdown-tool - Convert HTML↔Markdown

Schema Management (ENABLE_SCHEMA_MANAGEMENT=true)

Advanced tools for database schema modifications using Directus's built-in schema migration API. Use with caution - these tools can modify your database structure.

Tools:

• schema-snapshot - Get current database schema as JSON snapshot
• schema-diff - Compare target schema against current database, returns required changes
• schema-apply - Apply schema diff to database (destructive operation)
• add-unique-constraint - Add unique constraint to a field

Use Cases:

| Use Case | Tools | Description | |----------|-------|-------------| | Schema Backup | schema-snapshot | Export complete schema before major changes | | Environment Sync | snapshot → diff → apply | Migrate schema from dev to staging/production | | Data Integrity | add-unique-constraint | Enforce uniqueness (e.g., email, phone, SKU) | | Migration Preview | schema-diff | See exactly what will change before applying | | Schema Versioning | schema-snapshot | Store snapshots in git for version control | | CI/CD Pipelines | All tools | Automate schema deployments |

Workflow Examples:

1. Add unique constraint to prevent duplicate emails:

Ask Claude: "Make the email field unique in the users collection"
→ Uses add-unique-constraint tool

2. Sync schema between environments:

1. Get snapshot from production: schema-snapshot
2. Compare with staging: schema-diff (with prod snapshot)
3. Review changes, then apply: schema-apply

3. Schema backup before risky changes:

Ask Claude: "Take a schema snapshot before we modify the orders table"
→ Returns JSON that can be stored/versioned

Setup:

claude mcp add directus \
  -e DIRECTUS_URL=https://your-instance.com \
  -e DIRECTUS_TOKEN=your-token \
  -e READ_ONLY=false \
  -e ENABLE_SCHEMA_MANAGEMENT=true \
  -- npx -y @informatiktirol/anthrop-api-mcp

Example: Add unique constraint

{
  "collection": "users",
  "field": "email"
}

Important Limitations:

• Schema Management tools work only with user collections, not with Directus system tables (directus_users, directus_files, etc.)
• For system tables or when the API fails, use direct SQL: ALTER TABLE <table> ADD UNIQUE INDEX idx_<field>_unique (<field>);
• The add-unique-constraint tool will show a fallback SQL command if the API operation fails

Tool Parameter Reference

For detailed parameter schemas, see source code or use help-token-efficient tool.

Common patterns:

users-me requires fields parameter:

{ "fields": ["id", "email", "first_name", "last_name"] }

read-items with query parameters:

{
  "collection": "posts",
  "query": {
    "fields": ["id", "title", "status"],
    "limit": 10,
    "filter": { "status": { "_eq": "published" } },
    "sort": ["-date_created"]
  }
}

See src/tools/ for complete implementations.

Usage Best Practices

1. Start with discovery tools - Use list-collections and count-items before loading schema
2. Use targeted schema queries - Prefer read-collection-schema for single collections
3. Set appropriate limits - Default (unlimited) for daily use, limited for token efficiency
4. Limit item queries - Keep results under 10-20 items when possible
5. Use field filters - Specify only needed fields in read-items

Collection Selection Logic

Collections are processed alphabetically (after filtering):

1. Internal directus_* collections are skipped (except directus_files and directus_users)
2. Collections in SCHEMA_EXCLUDE_COLLECTIONS are skipped
3. First MAX_SCHEMA_COLLECTIONS collections are included
4. Selection is deterministic - always same collections with same settings

Development

For local development with hot reload:

# Clone repository
git clone [email protected]:informatikTirol/anthrop.api_mcp.git
cd anthrop.api_mcp

# Install dependencies
pnpm install

# Build
pnpm build

# See CLAUDE.md for detailed development instructions

Note: tsx watch does not work with MCP due to stdout pollution. Use compiled version (node ./dist/index.js).

See CLAUDE.md for detailed development workflow and architecture documentation.

Architecture

• Entry Point: src/index.ts - MCP server initialization
• Tools: src/tools/ - All MCP tool definitions
• Schema: src/utils/fetch-schema.ts - Lazy schema loading with limits
• Config: src/config.ts - Environment variable configuration

Key design decisions:

• Lazy loading: Schema not loaded at startup
• Token efficiency: Configurable limits prevent excessive token usage
• Granular access: Single collection queries available
• Safe field creation: Automatic interface defaults prevent broken UI

Related Documentation

• CLAUDE.md - Developer documentation and architecture guide
• DEPLOYMENT.md - npm distribution and release workflow
• ERD-DIAGRAM-V2.md - Complete ERD with all collections (requires full schema config)

License

MIT

Acknowledgments

Based on the Directus MCP Server by the Directus team, with token efficiency and performance optimizations.

Maintained by informatikTirol.