npm package: @informatiktirol/anthrop-api-mcp
Description: MCP server for Directus CMS integration - enables LLMs to interact with Directus instances.
Author: informatik_tirol
Latest version: 1.6.3

# anthrop.works Directus MCP Server

A token-efficient [Model Context Protocol](https://modelcontextprotocol.io) (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)

```bash
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`:

```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/anthrop-api-mcp@1.0.0`

## Complete Configuration Reference

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

```bash
claude mcp add directus \
  -e DIRECTUS_URL=https://your-directus-instance.com \
  -e DIRECTUS_TOKEN=your-api-token \
  \
  # Authentication (alternative to token)
  # -e DIRECTUS_USER_EMAIL=user@example.com \
  # -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 \
  # -e ENABLE_COLLECTION_TOOLS=false \
  # -e ENABLE_SCHEMA_MANAGEMENT=false \
  # -e ENABLE_ACCESS_CONTROL_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)**

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

**Option 2: Email/Password**

```bash
DIRECTUS_URL=https://your-instance.com
DIRECTUS_USER_EMAIL=user@example.com
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**

```bash
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:

```bash
# 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`
- `create-relation`, `update-relation` (requires `ENABLE_COLLECTION_TOOLS=true`)

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

```bash
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 collection/schema/access control) | Respects READ_ONLY         |
| `ENABLE_COLLECTION_TOOLS` | `false` | `create-collection`, `update-collection`, `create-relation`, `update-relation` | Requires READ_ONLY=false, must be explicitly enabled |
| `ENABLE_SCHEMA_MANAGEMENT` | `false` | `schema-snapshot`, `schema-diff`, `schema-apply`, `add-unique-constraint` | Requires READ_ONLY=false, must be explicitly enabled |
| `ENABLE_ACCESS_CONTROL_TOOLS` | `false` | `roles`, `policies`, `permissions`                              | 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
- Collection management, schema management, and access control tools are **intentionally excluded** from `ENABLE_ALL_TOOLS` - they must be explicitly enabled due to their database-modifying nature

**Example: Enable all tools in read-only mode**

```bash
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**

```bash
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

```bash
# 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)
- `refresh-schema` - Force-reload cached schema (use after external changes)

**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 user-created collection (default limit: 5, configurable). For core collections use dedicated tools (e.g. `read-users`, `read-files`)
- `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, supports M2O/file relations (requires READ_ONLY=false)
- `update-field` - Modify existing fields (requires READ_ONLY=false)

**Relations:**
- `read-relations` - Read existing foreign key relationships between collections

**User:**
- `users-me` - Get current user info (requires `fields` parameter)

---

### Optional Tools (Disabled by Default)

Enable via environment variables. See [Optional Tool Groups](#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

#### Collection Management (`ENABLE_COLLECTION_TOOLS=true`)

Tools for creating and configuring Directus collections (database tables). **Use with caution - these tools create real database tables.**

**Tools:**
- `create-collection` - Create new collection (database table) or folder (virtual collection)
- `update-collection` - Update collection metadata (icon, note, display template, grouping, etc.)
- `create-relation` - Create foreign key relationships with full control over metadata and schema (requires READ_ONLY=false)
- `update-relation` - Modify existing relation metadata or FK constraint behavior (requires READ_ONLY=false)

**Note:** `list-collections`, `read-collection-schema`, and `read-relations` are always available as core tools.

**Capabilities:**
- Create real database tables with customizable metadata
- Create virtual folders (`schema: null`) for organizing collections
- Update icons, colors, notes, display templates
- Group collections under folders via `meta.group`
- Set navigation sort order for folders via `meta.sort`
- Configure archiving, accountability, versioning settings

**Setup:**

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

**Example: Create a collection**
```json
{
  "data": {
    "collection": "blog_posts",
    "meta": {
      "icon": "article",
      "note": "Blog posts collection",
      "display_template": "{{title}}"
    },
    "schema": {}
  }
}
```

**Example: Create a folder and group collections**
```json
// Create folder
{ "data": { "collection": "content", "meta": { "icon": "folder" }, "schema": null } }

// Move collection into folder
{ "collection": "blog_posts", "data": { "meta": { "group": "content" } } }
```

**Example: Create a M2O relation with O2M alias on parent**
```json
{
  "collection": "posts",
  "field": "author",
  "related_collection": "directus_users",
  "meta": { "one_field": "posts" },
  "schema": { "on_delete": "SET NULL" }
}
```

**Example: Update an existing relation**
```json
{
  "collection": "posts",
  "field": "author",
  "schema": { "on_delete": "CASCADE" }
}
```

**Relation vs Field creation:**
- Use `create-field` with `related_collection` for simple M2O relations (creates field + relation in one step)
- Use `create-relation` when you need `one_field` (O2M alias), `junction_field` (M2M), `on_delete`, or `sort_field`

**Limitations:**
- `meta.sort` only works for folder collections (`schema: null`), not regular database tables
- Collection names cannot be changed after creation
- Delete collection and delete relation are not available via MCP (use Directus UI)

---

#### 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:**

```bash
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**
```json
{
  "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:
```json
{ "fields": ["id", "email", "first_name", "last_name"] }
```

`read-items` with query parameters:
```json
{
  "collection": "posts",
  "query": {
    "fields": ["id", "title", "status"],
    "limit": 10,
    "filter": { "status": { "_eq": "published" } },
    "sort": ["-date_created"]
  }
}
```

`create-field` for M2O relation (links to another collection):
```json
{
  "collection": "posts",
  "data": {
    "field": "author",
    "type": "uuid",
    "related_collection": "directus_users"
  }
}
```

`create-field` for file/image field:
```json
{
  "collection": "posts",
  "data": {
    "field": "featured_image",
    "type": "uuid",
    "related_collection": "directus_files"
  }
}
```

See [src/tools/](./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:

```bash
# Clone repository
git clone git@github.com: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](./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
- **Auto cache invalidation**: Schema cache refreshes automatically when a collection is not found (handles collections created mid-session via REST API or Directus UI)
- **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](./CLAUDE.md) - Developer documentation and architecture guide
- [DEPLOYMENT.md](./DEPLOYMENT.md) - npm distribution and release workflow
- [ERD-DIAGRAM-V2.md](./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.