directus-mcp-server

@staminna/directus-mcp-server

适用于 Directus 12 的 MCP 服务，提供 items、collections、files、flows、users 和 schema 工具。全程使用 TypeScript，并提供类型定义。

测试覆盖率

语句	分支	函数	行

覆盖率徽章由 npm run badges 根据 coverage/coverage-summary.json 生成（无需外部服务）。请先运行 npm run test:coverage。

功能

• 🔐 完整身份验证 - 使用 Directus 进行基于令牌的身份验证
• 📦 集合管理 - 对集合和条目执行 CRUD 操作
• 📁 文件操作 - 上传、下载和管理文件
• 🔄 Flow 管理 - 创建、更新、触发和管理 Directus Flows
• 👥 用户管理 - 用户 CRUD 和角色管理
• 🔍 Schema 工具 - 分析和验证集合 schema
• 🩺 诊断 - 集合访问诊断与故障排查

安装

通过 npm 安装（推荐）

npm install -g @staminna/directus-mcp-server

从源码安装

git clone https://github.com/staminna/mcp-server-claude.git
cd mcp-server-claude
npm install
npm run build

环境变量

变量	必需	描述
DIRECTUS_URL	是	Directus 实例的 URL（例如，http://localhost:8065）
DIRECTUS_TOKEN	是	具有适当权限的静态 API 令牌
DIRECTUS_PROMPTS_COLLECTION_ENABLED	否	启用 AI 提示词集合（true/false）
DIRECTUS_PROMPTS_COLLECTION	否	AI 提示词的集合名称（默认值：ai_prompts）
DIRECTUS_RESOURCES_ENABLED	否	启用资源功能（true/false）
DIRECTUS_RESOURCES_EXCLUDE_SYSTEM	否	从资源中排除系统集合（true/false）
NODE_ENV	否	环境模式（development/production）
DIRECTUS_TIMEOUT	否	请求超时时间，单位为毫秒（默认值：30000）
DIRECTUS_RETRIES	否	网络错误、5xx 和 429 的重试次数（默认值：3）
DIRECTUS_RETRY_DELAY	否	基础退避延迟，单位为毫秒（默认值：1000）
DIRECTUS_MAX_RETRY_DELAY	否	退避延迟上限，单位为毫秒（默认值：10000）
DIRECTUS_IMPORT_MAX_FILE_SIZE	否	客户端导入文件大小上限，单位为字节，与 Directus 的 IMPORT_MAX_FILE_SIZE 保持一致（默认值：50 MB）
LOG_LEVEL	否	DEBUG/INFO/WARN/ERROR（默认值：INFO）。日志输出到 stderr；stdout 保留给 MCP 使用

TLS / 客户端证书

如果 Directus 实例使用私有 CA 或要求提供客户端证书，请设置这些变量。CA/CERT/KEY/PFX 均可接受文件路径或 PEM/DER 内容本身。

变量	描述
DIRECTUS_HTTPS_CA	证书颁发机构
DIRECTUS_HTTPS_CERT	客户端证书
DIRECTUS_HTTPS_KEY	客户端私钥
DIRECTUS_HTTPS_PFX	PKCS#12 包（可替代 cert/key）
DIRECTUS_HTTPS_PASSPHRASE	密钥或 PFX 的密码短语
DIRECTUS_HTTPS_REJECT_UNAUTHORIZED	设为 false 可接受自签名证书
DIRECTUS_HTTPS_SERVERNAME	覆盖 SNI 服务器名称

---

身份验证——无需 OAuth

此服务使用静态 Directus 访问令牌（DIRECTUS_TOKEN），并通过 stdio 传输运行。按照设计，无需使用 OAuth：

• MCP 规范仅为基于 HTTP 的传输定义 OAuth 2.1 授权。对于 stdio 服务，规范表示实现*"不应"*使用 OAuth，而应改为从环境中获取凭据——此服务正是如此。
• Directus 12 完全支持静态访问令牌。 Directus 新增的 OAuth 2.1 支持（2026 年年中）适用于其内置的远程 MCP 端点，而且是可选的；Directus 12 中的令牌身份验证没有任何破坏性变更（参见 DIRECTUS_V12_BREAKING_CHANGES.md）。
• 只有在通过 HTTP（Streamable HTTP/SSE）远程公开 MCP 服务时，才需要考虑 OAuth。作为 Claude Desktop、Claude Code、Cursor 等的本地 stdio 子进程运行时，此服务只需要环境变量中的令牌。

在 Directus 的用户设置 → 令牌中生成令牌（生产环境中，请使用具有最小权限角色的专用用户）。

使用 Claude 订阅（Max/Pro）——无需 API 密钥

MCP 服务本身不会消耗 Anthropic API 令牌；只有 AI 客户端调用模型时才会消耗。如果你在订阅了 Claude Max（或 Pro）的 Claude Code 或 Claude Desktop 中使用此服务，模型用量由订阅涵盖——你无需 Anthropic API 密钥。只有通过 Claude API 以编程方式调用 Claude（例如，使用远程 MCP 连接器）时才需要 API 密钥。

---

IDE 配置

🟣 Cursor

1. 打开 Cursor 设置：Cmd+,（macOS）或 Ctrl+,（Windows/Linux）
2. 搜索 “MCP” 或前往 功能 → MCP 服务
3. 点击 “在 settings.json 中编辑”
4. 添加以下配置：

{
  "mcpServers": {
    "directus": {
      "command": "npx",
      "args": [
        "-y",
        "@staminna/directus-mcp-server"
      ],
      "env": {
        "DIRECTUS_URL": "http://localhost:8065",
        "DIRECTUS_TOKEN": "your-directus-token-here"
      }
    }
  }
}

或在本地安装时：

{
  "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. 保存文件并重启 Cursor

---

🌊 Windsurf

1. 打开 Windsurf 设置：Cmd+,（macOS）或 Ctrl+,（Windows/Linux）
2. 搜索 “MCP 服务”
3. 点击 “在 settings.json 中编辑”
4. 添加以下配置：

{
  "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"
      }
    }
  }
}

或在本地安装时：

{
  "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. 保存文件
6. 完全退出 Windsurf（Cmd+Q 或 Ctrl+Q）
7. 重新打开 Windsurf，并等待约 10 秒，让 MCP 完成初始化

---

🤖 Claude Desktop

1. 找到 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

2. 创建或编辑配置文件：

{
  "mcpServers": {
    "directus": {
      "command": "npx",
      "args": [
        "-y",
        "@staminna/directus-mcp-server"
      ],
      "env": {
        "DIRECTUS_URL": "http://localhost:8065",
        "DIRECTUS_TOKEN": "your-directus-token-here"
      }
    }
  }
}

或在本地安装时：

{
  "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. 保存文件并重启 Claude Desktop

---

🔮 Claude.ai（支持 MCP 的网页版）

要在支持 MCP 的 Claude.ai 网页界面中使用：

1. 前往 Claude.ai 设置
2. 找到 MCP 配置部分
3. 添加一个新的 MCP 服务，并填写：

{
  "name": "directus",
  "command": "npx",
  "args": ["-y", "@staminna/directus-mcp-server"],
  "env": {
    "DIRECTUS_URL": "http://localhost:8065",
    "DIRECTUS_TOKEN": "your-directus-token-here"
  }
}

注意：Claude.ai 的 MCP 支持可能需要 Pro 订阅和特定的浏览器扩展。

---

可用工具

集合管理

工具	描述
list_collections	列出所有集合；文件夹和非活动集合（Directus 12.4）会标记出来
get_collection_schema	获取指定集合的架构
get_collection_items	获取集合中的项目，支持筛选
create_collection	创建新集合
delete_collection	删除集合（需要 confirm）
create_item	在集合中创建新项目
update_item	更新现有项目，也可将其更新到草稿 version
delete_items	按 ids 或 query 删除项目（参见下方说明）
bulk_operations	执行批量创建、更新和删除

架构与字段

工具	描述
create_field	在集合中创建新字段
update_field	更新现有字段
delete_field	从集合中删除字段
create_relationship	创建关系（O2O、O2M、M2O、M2M、M2A）
analyze_collection_schema	分析架构并映射关系
validate_collection_schema	验证架构和关系
analyze_relationships	分析各集合之间的关系
get_schema_snapshot	读取数据模型的完整或部分快照
diff_schema	将快照与实时架构进行比较（merge 或 mirror）。Directus 会丢弃超过约 96 KB 的请求正文，因此对于规模较大的数据模型，请使用 get_schema_snapshot 中带有 include_collections 的部分快照 — 参见 DIRECTUS_V12_BREAKING_CHANGES.md
apply_schema	应用差异（需要 confirm）

流程管理

工具	描述
get_flows	获取所有流程，也可按 folder 筛选（Directus 12.4）
get_flow	按 ID 获取指定流程
create_flow	创建新的自动化流程，也可在 folder 中创建
update_flow	更新现有流程
delete_flow	删除流程
trigger_flow	手动触发流程
get_operations	获取流程操作

用户管理

工具	描述
get_users	获取所有用户，支持筛选
get_user	按 ID 获取指定用户

文件管理

工具	描述
get_files	获取文件，支持筛选和分页
import_data	将 CSV/JSON 导入一个或多个集合

诊断

工具	描述
diagnose_collection_access	诊断集合访问问题
refresh_collection_cache	刷新集合缓存
validate_collection_creation	验证新创建的集合

发现

工具	描述
search_tools	根据任务描述查找匹配的工具

工具安全注释

每个工具都带有 MCP 注释，以便客户端在调用前区分读取和写入操作：17 个工具设有 readOnlyHint: true，6 个工具明确设有 destructiveHint: false（仅追加 — 创建），11 个工具设有 destructiveHint: true（删除、覆盖式更新、apply_schema、import_data、trigger_flow）。

请注意，MCP 规范中 destructiveHint 默认值为 true，因此仅追加的工具会将其设为 false，而不是省略。

安全删除项目

根据 Directus 12.3.0 的行为，delete_items 绝不会退而删除所有项目：

• ids: [...] 会删除这些项目。
• query: {...} 会删除所有符合查询条件的项目。
• 同时传入两者会被拒绝。
• 两者都不传则不会删除任何项目，也不会发出请求。

若要删除集合中的所有项目，请明确提出要求：

{ "collection": "articles", "query": { "limit": -1 }, "confirm": true }

自 Directus 12.4.0 起，query 会根据令牌的读取权限解析目标：必须具有主键的读取权限，且只会删除令牌可读取的项目。只有删除权限、没有读取权限的令牌不会删除任何项目。

---

使用示例

完成配置后，即可通过 AI 助手与 Directus 交互：

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

---

故障排除

MCP 服务无法连接

1. 确认 Directus 正在运行：确保可以通过配置的 URL 访问你的 Directus 实例
2. 检查令牌权限：API 令牌需要具备执行所需操作的相应权限
3. 重启 IDE：更改 MCP 配置后，完全重启 IDE
4. 检查日志：查看 IDE 开发者控制台中是否有 MCP 相关错误

权限错误

确保你的 Directus 令牌具备所需权限：

• 使用管理员令牌以获得完整访问权限
• 或为需要访问的集合配置特定角色权限

连接超时

如果使用远程 Directus 实例：

• 确认 URL 正确且可以访问
• 检查防火墙／网络设置
• 确保 Directus 上已正确配置 CORS

---

开发

# 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

测试

项目提供单元、集成和端到端测试套件（vitest）。测试覆盖率阈值（语句／行／函数／分支均为 95%）会强制执行——测试运行未达到阈值时将失败。

# Unit + integration tests
npm test

# With coverage report (coverage/ — text, html, lcov, json-summary)
npm run test:coverage

# End-to-end: builds, then spawns the real server over stdio against a mock Directus
npm run test:e2e

# Everything
npm run test:all

# Refresh the README coverage badges from the last coverage run
npm run badges

针对真实 Directus 进行实时验证

tests/live/demo.mjs 通过标准输入／输出，使用真实实例测试全部 34 个工具。该测试特意不纳入 npm test——它需要凭据和可访问的服务，因此是手动检查环节，而非 CI 检查环节。

# Read-only + guard phases (touches nothing)
ENV_FILE=.env.mdbaudio npm run test:live

# Also create, mutate and drop a scratch mcp_demo_<stamp> collection
ENV_FILE=.env.mdbaudio npm run test:live -- --write

# Additionally exercise apply_schema, confined to that scratch collection
ENV_FILE=.env.mdbaudio npm run test:live -- --write --apply-schema

凭据从 ENV_FILE 读取（默认为 .env.mdbaudio），因此不会经过 shell 历史记录。每个工具的结果会报告为通过／被实例拒绝／失败，从而区分“服务有问题”和“实例拒绝了操作”。--apply-schema 以合并模式进行差异比对，生成严格的增量差异，因此只能重新创建临时集合，不能删除任何已有内容。即使较早阶段失败，也会执行清理。

端到端测试套件使用官方 MCP SDK 客户端（StdioClientTransport），将 dist/index.js 作为子进程启动，并通过临时端口与进程内模拟 Directus 通信——无需真实 Directus 实例或网络访问。

---

参与贡献

欢迎贡献！欢迎提交 Pull Request。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

---

许可证

MIT © Jorge Domingues Nunes

---

链接

• npm 程序包
• GitHub 仓库
• Directus 文档
• MCP 协议规范