使用说明

Directus MCP服务器

一种模型上下文协议（MCP）服务器，为管理Directus模式和内容提供了全面的工具。此服务器使AI助手和其他MCP客户端能够以编程方式与Directus实例交互。

安装

来自npm（一旦发布）

npm install -g directus-mcp-server

来源

git clone https://github.com/yourusername/directus-mcp.git
cd directus-mcp
npm install
npm run build

特性

模式管理：创建、读取、更新和删除集合、字段和关系
内容管理：使用高级查询对项目进行完整的CRUD操作
类型安全：使用TypeScript和Zod验证构建
官方SDK：使用官方 @directus/sdk 用于可靠的API交互
灵活的身份验证：支持静态令牌和电子邮件/密码身份验证

安装

npm install

配置

创建一个 .env 根目录中具有Directus配置的文件：

# Directus Instance URL
DIRECTUS_URL=https://your-directus-instance.com

# Authentication - Use either token OR email/password
DIRECTUS_TOKEN=your_static_token_here

# Alternative: Email/Password authentication
# DIRECTUS_EMAIL=admin@example.com
# DIRECTUS_PASSWORD=your_password

身份验证选项

静态令牌 （推荐用于生产）：
- 在Directus管理应用程序中生成静态令牌
- 集 DIRECTUS_TOKEN 环境变量
电子邮件/密码:
- 用于开发或静态令牌不可用时
- 集 DIRECTUS_EMAIL 和 DIRECTUS_PASSWORD 环境变量

工具集配置

Directus MCP服务器将工具组织成逻辑工具集，类似于GitHub的MCP实现。这允许您控制哪些工具暴露给MCP客户端。

可用工具集：

default -包含集合、字段、关系和内容工具（未指定工具集时的默认行为）
collections -收藏管理工具（列表、获取、创建、更新、删除收藏）
fields -字段管理工具（列出、创建、更新、删除字段）
relations -关系管理工具（列出、创建、删除关系）
schema -模式快照和差异工具（获取快照、获取差异、应用差异）-不包含在默认工具集中
content -内容管理工具（项目CRUD操作）
flow -流管理工具（工作流自动化）-不包含在默认工具集中
dashboards -仪表板和面板管理工具（列表、获取、创建、更新、删除仪表板和板）-不包含在默认工具集中
all -所有可用工具，无论工具集成员身份如何

默认行为： 当 MCP_TOOLSETS 未设置或为空，只有工具 default 工具集已公开。这 default 工具集包含集合、字段、关系和内容工具，但是不模式、流或仪表板工具。必须通过包括以下内容来明确请求架构、流和仪表板工具 schema, flow，或 dashboards 在 MCP_TOOLSETS 环境变量。

配置： 设置 MCP_TOOLSETS 将环境变量转换为逗号分隔的工具集列表：

# Expose only collections tools
MCP_TOOLSETS=collections

# Expose only schema snapshot/diff tools
MCP_TOOLSETS=schema

# Expose collections and fields tools
MCP_TOOLSETS=collections,fields

# Expose only dashboard and panel tools
MCP_TOOLSETS=dashboards

# Expose all schema-related toolsets
MCP_TOOLSETS=collections,fields,relations,schema

# Expose all toolsets (includes flow and dashboard tools)
MCP_TOOLSETS=default,flow,dashboards
# OR
MCP_TOOLSETS=collections,fields,relations,schema,content,flow,dashboards
# OR simply use 'all' to expose everything
MCP_TOOLSETS=all

示例：

{
  "mcpServers": {
    "directus-schema": {
      "command": "node",
      "args": ["/path/to/directus-mcp/dist/index.js"],
      "env": {
        "DIRECTUS_URL": "https://your-directus-instance.com",
        "DIRECTUS_TOKEN": "your_token",
        "MCP_TOOLSETS": "schema"
      }
    },
    "directus-content": {
      "command": "node",
      "args": ["/path/to/directus-mcp/dist/index.js"],
      "env": {
        "DIRECTUS_URL": "https://your-directus-instance.com",
        "DIRECTUS_TOKEN": "your_token",
        "MCP_TOOLSETS": "content"
      }
    }
  }
}

笔记：

工具集名称不区分大小写
无效的工具集名称将被忽略（并带有警告）
如果所有请求的工具集都无效，则服务器默认为 default 工具集
集合、字段、关系和内容工具属于这两者 default 以及他们的特定工具集
模式、流程和仪表板工具仅属于其各自的工具集（不在 default)

建筑

npm run build

用法

运行服务器

npm start

或者使用内置的二进制文件：

node dist/index.js

MCP客户端配置

添加到您的MCP客户端配置中（例如，Claude Desktop、Cline）：

选项1：使用npx（推荐-无需安装）：

{
  "mcpServers": {
    "directus": {
      "command": "npx",
      "args": ["-y", "directus-mcp-server"],
      "env": {
        "DIRECTUS_URL": "https://your-directus-instance.com",
        "DIRECTUS_TOKEN": "your_static_token_here",
        "MCP_TOOLSETS": "default"
      }
    }
  }
}

选项2：使用全局安装：

{
  "mcpServers": {
    "directus": {
      "command": "directus-mcp",
      "env": {
        "DIRECTUS_URL": "https://your-directus-instance.com",
        "DIRECTUS_TOKEN": "your_static_token_here",
        "MCP_TOOLSETS": "default"
      }
    }
  }
}

选项3：使用本地来源：

{
  "mcpServers": {
    "directus": {
      "command": "node",
      "args": ["/absolute/path/to/directus-mcp/dist/index.js"],
      "env": {
        "DIRECTUS_URL": "https://your-directus-instance.com",
        "DIRECTUS_TOKEN": "your_static_token_here",
        "MCP_TOOLSETS": "default"
      }
    }
  }
}

可用工具

架构管理工具

`list_collections`

列出Directus实例中的所有集合。

参数：无

示例:

{}

`get_collection`

获取特定收藏的详细信息。

参数:

collection （string）：集合名称

示例:

{
  "collection": "articles"
}

`create_collection`

使用可选字段创建新的集合（数据库表）。这会自动创建一个适当的数据库表，而不仅仅是一个文件夹。

参数:

collection （string）：集合名称
meta （对象，可选）：集合元数据（图标、注释、单例等）
schema （对象，可选）：数据库架构配置（如果未提供，则自动设置）
fields （数组，可选）：要创建的初始字段

示例:

{
  "collection": "articles",
  "meta": {
    "icon": "article",
    "note": "Blog articles collection"
  },
  "fields": [
    {
      "field": "id",
      "type": "integer",
      "schema": {
        "is_primary_key": true,
        "has_auto_increment": true
      }
    },
    {
      "field": "title",
      "type": "string",
      "meta": {
        "required": true
      }
    },
    {
      "field": "status",
      "type": "string",
      "meta": {
        "interface": "select-dropdown",
        "options": {
          "choices": [
            {"text": "Draft", "value": "draft"},
            {"text": "Published", "value": "published"}
          ]
        }
      }
    }
  ]
}

`update_collection`

更新集合元数据。

参数:

collection （string）：集合名称
meta （对象）：要更新的元数据

示例:

{
  "collection": "articles",
  "meta": {
    "icon": "article",
    "note": "Updated description"
  }
}

`delete_collection`

删除集合及其所有数据。

参数:

collection （string）：集合名称

示例:

{
  "collection": "articles"
}

`list_fields`

列出集合中的所有字段。

参数:

collection （string）：集合名称

示例:

{
  "collection": "articles"
}

`create_field`

向集合中添加新字段。

参数:

collection （string）：集合名称
field （string）：字段名称
type （string）：字段类型（字符串、整数、文本、布尔值、json、uuid、时间戳等）
meta （对象，可选）：字段元数据
schema （对象，可选）：数据库架构配置

示例:

{
  "collection": "articles",
  "field": "author",
  "type": "uuid",
  "meta": {
    "interface": "select-dropdown-m2o",
    "required": true,
    "special": ["m2o"]
  }
}

`update_field`

更新字段属性。

参数:

collection （string）：集合名称
field （string）：字段名称
type （字符串，可选）：字段类型
meta （对象，可选）：要更新的元数据
schema （对象，可选）：要更新的架构

示例:

{
  "collection": "articles",
  "field": "title",
  "meta": {
    "note": "Article title (required)"
  }
}

`delete_field`

从集合中删除字段。

参数:

collection （string）：集合名称
field （string）：字段名称

示例:

{
  "collection": "articles",
  "field": "old_field"
}

`list_relations`

列出Directus实例中的所有关系。

参数：无

示例:

{}

`create_relation`

在集合之间创建关系。

参数:

collection （string）：多个集合（带外键）
field （string）：多个集合中的字段名
related_collection （字符串，可选）：一个集合
meta （对象，可选）：关系元数据
schema （对象，可选）：数据库关系配置

示例（多对一）:

{
  "collection": "articles",
  "field": "author",
  "related_collection": "users",
  "schema": {
    "on_delete": "SET NULL"
  }
}

示例（一对多）:

{
  "collection": "articles",
  "field": "author",
  "related_collection": "users",
  "meta": {
    "one_field": "articles"
  }
}

`delete_relation`

删除关系。

参数:

collection （string）：集合名称
field （string）：字段名称

示例:

{
  "collection": "articles",
  "field": "author"
}

内容管理工具

`query_items`

通过过滤、排序和分页查询项目。

参数:

collection （string）：集合名称
fields （数组，可选）：要返回的字段
filter （对象，可选）：筛选条件
search （字符串，可选）：搜索查询
sort （数组，可选）：对字段进行排序（前缀为 - 下降）
limit （数字，可选）：可退回的最大项目数
offset （数字，可选）：要跳过的项目
page （数字，可选）：页码
aggregate （对象，可选）：聚合函数
groupBy （数组，可选）：按字段分组
deep （对象，可选）：深度关系查询

过滤器操作员: _eq, _neq, _lt, _lte, _gt, _gte, _in, _nin, _null, _nnull, _contains, _ncontains, _starts_with, _nstarts_with, _ends_with, _nends_with, _between, _nbetween

示例:

{
  "collection": "articles",
  "filter": {
    "status": {"_eq": "published"},
    "date_created": {"_gte": "2024-01-01"}
  },
  "sort": ["-date_created"],
  "limit": 10
}

`get_item`

按ID获取单个项目。

参数:

collection （string）：集合名称
id （字符串|数字）：项目ID
fields （数组，可选）：要返回的字段
deep （对象，可选）：深度关系查询

示例:

{
  "collection": "articles",
  "id": 1,
  "fields": ["id", "title", "status", "author.first_name"]
}

`create_item`

创建新项目。

参数:

collection （string）：集合名称
data （对象）：项目数据

示例:

{
  "collection": "articles",
  "data": {
    "title": "My New Article",
    "status": "draft",
    "body": "Article content here...",
    "author": "user-uuid-here"
  }
}

`update_item`

更新现有项目。

参数:

collection （string）：集合名称
id （字符串|数字）：项目ID
data （对象）：要更新的字段

示例:

{
  "collection": "articles",
  "id": 1,
  "data": {
    "status": "published"
  }
}

`delete_item`

删除项目。

参数:

collection （string）：集合名称
id （字符串|数字）：项目ID

示例:

{
  "collection": "articles",
  "id": 1
}

`bulk_create_items`

一次创建多个项目。

参数:

collection （string）：集合名称
items （array）：项目数据对象数组

示例:

{
  "collection": "articles",
  "items": [
    {"title": "Article 1", "status": "draft"},
    {"title": "Article 2", "status": "draft"}
  ]
}

`bulk_update_items`

一次更新多个项目。

参数:

collection （string）：集合名称
items （array）：具有id和要更新的字段的项目数组

示例:

{
  "collection": "articles",
  "items": [
    {"id": 1, "status": "published"},
    {"id": 2, "status": "published"}
  ]
}

`bulk_delete_items`

一次删除多个项目。

参数:

collection （string）：集合名称
ids （array）：项目ID数组

示例:

{
  "collection": "articles",
  "ids": [1, 2, 3]
}

常见用例

建立新的内容模型

创建一个集合 create_collection
添加字段 create_field
与建立关系 create_relation
开始添加内容 create_item

查询带有关系的内容

{
  "collection": "articles",
  "fields": ["*", "author.first_name", "author.last_name"],
  "filter": {"status": {"_eq": "published"}},
  "sort": ["-date_created"],
  "limit": 10
}

批量操作

使用 bulk_create_items, bulk_update_items，或 bulk_delete_items 用于高效的批处理操作。

发展

# Watch mode for development
npm run dev

# Build for production
npm run build

工具编写

该项目提供了简化MCP工具开发和减少代码重复的实用程序：

工具助手

使用 createTool 用于返回数据的工具，以及 createActionTool 对于执行操作的工具：

import { createTool, createActionTool } from './tools/tool-helpers.js';

// Data-returning tool
const myTool = createTool({
  name: 'my_tool',
  description: 'Description of what the tool does',
  inputSchema: MySchema,
  toolsets: ['default', 'my-category'],
  handler: async (client, args) => client.someMethod(args)
});

// Action tool (returns success message)
const myActionTool = createActionTool({
  name: 'delete_something',
  description: 'Delete something',
  inputSchema: DeleteSchema,
  toolsets: ['default'],
  handler: async (client, args) => client.deleteMethod(args.id),
  successMessage: (args) => `Successfully deleted item ${args.id}`
});

共享验证器

常见的Zod模式可在 src/tools/validators.ts:

CollectionNameSchema -对于集合名称
ItemIdSchema -对于项目ID（字符串|数字）
FieldsSchema -对于字段数组
FilterSchema -对于Directus筛选器对象
查询参数架构(SortSchema, LimitSchema等等）
流相关模式(FlowTriggerSchema, FlowStatusSchema等等）

示例用法：

import { CollectionNameSchema, ItemIdSchema } from './tools/validators.js';

const MyToolSchema = z.object({
  collection: CollectionNameSchema,
  id: ItemIdSchema,
  // ... other fields
});

Directus客户端资源工厂

客户端使用资源工厂模式进行一致的CRUD操作。添加新的Directus资源时，在客户端构造函数中使用 createResourceMethods().

错误处理

所有工具都包括错误处理，并将返回以下描述性错误消息：

身份验证失败
无效参数
API错误
网络问题
验证错误

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交拉取请求。

使用说明

Directus MCP服务器

安装

来自npm（一旦发布）

来源

特性

安装

配置

身份验证选项

工具集配置

建筑

用法

运行服务器

MCP客户端配置

可用工具

架构管理工具

list_collections

get_collection

create_collection

update_collection

delete_collection

list_fields

create_field

update_field

delete_field

list_relations

create_relation

delete_relation

内容管理工具

query_items

get_item

create_item

update_item

delete_item

bulk_create_items

bulk_update_items

bulk_delete_items