Directus MCP Server

Directus MCP 服务

一个为 Directus CMS 实现 Model Context Protocol (MCP) 的 Node.js 服务。让 AI 客户端能够通过 Model Context Protocol (MCP) 与 Directus API 交互。

ℹ 前置条件

• Node.js
• NPM
• 一个 Directus 实例

▶️ 快速开始

1. 获取你的 Directus API 凭据

   • 前往你的 Directus 实例
   • 创建静态访问令牌，或获取你的邮箱和密码
   • 请妥善保管这些凭据

2. 添加到你的 AI 编辑器

   {
     "mcpServers": {
       "directus": {
         "command": "npx",
         "args": ["-y", "@pixelsock/directus-mcp@latest"],
         "env": {
           "DIRECTUS_URL": "https://your-directus-instance.com",
           "DIRECTUS_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN"
         }
       }
     }
   }
   

   或者，你可以使用邮箱/密码认证：

   {
     "mcpServers": {
       "directus": {
         "command": "npx",
         "args": ["-y", "@pixelsock/directus-mcp@latest"],
         "env": {
           "DIRECTUS_URL": "https://your-directus-instance.com",
           "DIRECTUS_EMAIL": "[email protected]",
           "DIRECTUS_PASSWORD": "your-password"
         }
       }
     }
   }
   

   适用于 Cursor：

   1. 前往 Settings → Cursor Settings → MCP
   2. 点击 + Add New Global MCP Server
   3. 粘贴配置
   4. 将占位符值替换为你的 Directus 凭据
   5. 保存并重启 Cursor

   适用于 Claude Desktop：

   1. 打开 Settings → Developer
   2. 点击 Edit Config
   3. 在代码编辑器中打开 claude_desktop_config.json 并粘贴配置
   4. 将占位符值替换为你的 Directus 凭据
   5. 保存并重启 Claude

❓ 故障排查

如果你在 MCP 客户端（例如 Cursor 或 Claude Desktop）中启动服务时遇到问题，请尝试以下方法。

确保你的 Directus 凭据有效

1. 验证你的 Directus URL 正确且可访问
2. 检查你的访问令牌或邮箱/密码凭据是否有效
3. 在 MCP 客户端配置中替换这些凭据
4. 保存并重启你的 MCP 客户端

确保已安装 Node 和 NPM

• Node.js
• NPM

运行以下命令以确认你已安装 Node 和 NPM：

node -v
npm -v

清除 NPM 缓存

有时清除你的 NPM 缓存可以解决 npx 的问题。

npm cache clean --force

🛠️ 可用工具

集合与项目

getItems                // Get items from a collection
getItem                 // Get a single item from a collection by ID
createItem              // Create a new item in a collection
updateItem              // Update an existing item in a collection
deleteItem              // Delete an item from a collection
getCollections          // Get all collection schemas
getFields               // Get fields for a collection
getRelations            // Get relations for a collection

文件

getFiles                // Get files from Directus
uploadFile              // Upload a file to Directus

用户与权限

login                   // Login to Directus and get an access token
getUsers                // Get users from Directus
getCurrentUser          // Get the current user info
getRoles                // Get roles from Directus
getPermissions          // Get permissions from Directus

系统

getSystemInfo           // Get system information from Directus
getActivity             // Get activity logs from Directus
getConfig               // Get current configuration information

🚧 开发模式

如果你想以开发模式运行服务：

1. 克隆并安装：

   git clone https://github.com/pixelsock/directus-mcp.git
   cd directus-mcp
   npm install
   

2. 将你的凭据添加到 .env：

   # .env
   DIRECTUS_URL=https://your-directus-instance.com
   DIRECTUS_ACCESS_TOKEN=your_token_here
   # Or use email/password
   [email protected]
   DIRECTUS_PASSWORD=your-password
   

3. 启动开发服务：

   npm run dev
   

🌐 HTTP 传输（多用户 / 远程部署）

默认情况下，服务使用 stdio 传输，这非常适合单用户的本地 AI 编辑器（Cursor、Claude Desktop 等）。

对于多用户或远程环境，你可以通过设置 MCP_TRANSPORT 环境变量切换到 Streamable HTTP 传输。

配置

环境变量	默认值	描述
MCP_TRANSPORT	stdio	传输模式：stdio 或 http / streamable-http
MCP_PORT	3000	HTTP 服务监听的 TCP 端口
MCP_HOST	127.0.0.1	要绑定的主机/接口。使用 0.0.0.0 绑定所有接口

你也可以通过 CLI 参数传入 --transport=http，而不设置环境变量。

运行 HTTP 服务

# Via environment variable
MCP_TRANSPORT=http MCP_PORT=3000 MCP_HOST=0.0.0.0 node dist/index.js

# Via CLI argument
node dist/index.js --transport=http

Docker 示例

docker run -p 3000:3000 \
  -e DIRECTUS_URL=https://your-directus-instance.com \
  -e DIRECTUS_ACCESS_TOKEN=your_token_here \
  -e MCP_TRANSPORT=http \
  -e MCP_HOST=0.0.0.0 \
  ghcr.io/pixelsock/directus-mcp

将 MCP 客户端连接到 HTTP 服务

服务启动后，配置你的 MCP 客户端连接到：

http://<host>:<port>/mcp

例如，使用支持 Streamable HTTP 传输的客户端：

{
  "mcpServers": {
    "directus": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

📄 Directus 开发者资源

• Directus API 文档
• Directus API 端点
• Directus JavaScript SDK