Skip to main content
Glama

@staminna/directus-mcp-server

为 Directus 12 打造的 MCP 服务器 — 条目、集合、文件、流、用户和 schema 工具。使用 TypeScript 编写,全程类型化。

npm version License: MIT CI

测试覆盖率

语句

分支

函数

Statements

Branches

Functions

Lines

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

功能特性

  • 🔐 完整身份验证 - 基于令牌的 Directus 身份验证

  • 📦 集合管理 - 集合和条目的 CRUD 操作

  • 📁 文件操作 - 上传、下载和管理文件

  • 🔄 流管理 - 创建、更新、触发和管理 Directus Flows

  • 👥 用户管理 - 用户 CRUD 和角色管理

  • 🔍 Schema 工具 - 分析和验证集合的 schema

  • 🩺 诊断 - 集合访问诊断和故障排除

Related MCP server: Storyblok MCP Server

安装

通过 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 服务器,规范指出实现*“不应”*使用它,而应改为从环境中获取凭据 — 这正是本服务器所做的。

  • Directus 12 完全支持静态访问令牌。 Directus 添加的 OAuth 2.1 支持(2026 年中期)适用于其内置的远程 MCP 端点,并且是可选的;Directus 12 中没有对令牌身份验证的破坏性变更(参见 DIRECTUS_V12_BREAKING_CHANGES.md)。

  • 只有在您通过 HTTP 远程暴露 MCP 服务器(Streamable HTTP/SSE)时,OAuth 才会变得相关。作为 Claude Desktop、Claude Code、Cursor 等的本地 stdio 子进程,本服务器只需要环境令牌。

在 Directus 的用户设置 → 令牌下生成该令牌(生产环境请使用具有最小权限角色的专用用户)。

与 Claude 订阅(Max/Pro)一起使用 — 无需 API 密钥

MCP 服务器本身不消耗 Anthropic API 令牌;只有 AI 客户端的模型调用才会消耗。如果您在 Claude Code 或 Claude Desktop 中使用此服务器并拥有 Claude Max(或 Pro)订阅,模型使用量由订阅覆盖 — 您需要 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"
      }
    }
  }
}
  1. 保存文件并重启 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"
      }
    }
  }
}
  1. 保存文件

  2. 完全退出 WindsurfCmd+QCtrl+Q

  3. 重新打开 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"
      }
    }
  }
}
  1. 保存文件并重启 Claude Desktop


🔮 Claude.ai(支持 MCP 的 Web 版)

对于支持 MCP 的 Claude.ai Web 界面:

  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 中的所有集合

get_collection_schema

获取特定集合的 schema

get_collection_items

从集合中获取条目,支持过滤

create_collection

创建新集合

delete_collection

删除集合(需要 confirm

create_item

在集合中创建新条目

update_item

更新现有条目,也可选择更新至草稿 version

delete_items

idsquery 删除条目(参见下方说明)

bulk_operations

执行批量创建、更新、删除

Schema 与字段

工具

描述

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

将快照与实时架构进行比较(mergemirror)。Directus 会丢弃超过约 96 KB 的请求体,因此对于任何较大的数据模型,请使用 include_collections 传入来自 get_schema_snapshot 的部分快照——参见 DIRECTUS_V12_BREAKING_CHANGES.md

apply_schema

应用差异(需要 confirm

流程管理

工具

描述

get_flows

获取所有流程,可选择过滤

get_flow

按 ID 获取特定流程

create_flow

创建新的自动化流程

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_schemaimport_datatrigger_flow)。

请注意,在 MCP 规范中,destructiveHint 默认为 true,这就是为什么添加性工具将其设为 false 而不是省略它。

安全删除项目

从 Directus 12.3.0 开始,delete_items 绝不会回退为删除所有内容:

  • ids: [...] 删除这些项目。

  • query: {...} 删除查询匹配的所有内容。

  • 同时传入两者会被拒绝。

  • 两者都不传入则不删除任何内容,也不发出请求。

要删除集合中的所有项目,请明确请求:

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

使用示例

配置完成后,您可以通过 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 正在运行:确保你的 Directus 实例可通过配置的 URL 访问

  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 通过 stdio 驱动全部 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-schemamerge 模式进行差异比较,这会生成严格添加性的差异,因此它只能重新创建暂存集合——不能删除任何已存在的内容。即使早期阶段失败,清理也会运行。

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


贡献

欢迎贡献!请随时提交 Pull Request。

  1. 复刻仓库

  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


链接

Related MCP Servers

  • F
    license
    Not graded
    quality
    Not graded
    maintenance
    Enables comprehensive management of Storyblok CMS through natural language interactions. Supports story creation and publishing, asset management, component schema updates, release workflows, and content discovery across all major Storyblok APIs.
    10
  • A
    license
    A
    quality
    C
    maintenance
    Enables comprehensive management of Directus instances through tools for schema manipulation, content CRUD operations, and dashboard management. It allows AI assistants to programmatically interact with collections, fields, relations, and workflow automation using the official Directus SDK.
    20
    40
    MIT

View all related MCP servers

Related MCP Connectors

  • Manage Appwrite projects, databases, auth, storage, functions, and messaging; search Appwrite docs

  • AI-powered design and management for Webflow Sites

  • Manage SRG+ hubs, channels, content, assets, users, and workspaces from any MCP-aware AI agent.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/staminna/mcp-server-claude'

If you have feedback or need assistance with the MCP directory API, please join our Discord server