directus-mcp-server

@staminna/directus-mcp-server

Directus 12 用の MCP サーバーです。アイテム、コレクション、ファイル、フロー、ユーザー、スキーマ用のツールを備えています。TypeScript を全面的に使用し、型安全です。

テストカバレッジ

ステートメント	分岐	関数	行

カバレッジバッジは、外部サービスを必要とせず、npm run badges によって coverage/coverage-summary.json から生成されます。最初に npm run test:coverage を実行してください。

機能

• 🔐 完全な認証 - Directus でのトークンベース認証
• 📦 コレクション管理 - コレクションとアイテムの CRUD 操作
• 📁 ファイル操作 - ファイルのアップロード、ダウンロード、管理
• 🔄 フロー管理 - Directus フローの作成、更新、トリガー、管理
• 👥 ユーザー管理 - ユーザーの CRUD とロール管理
• 🔍 スキーマツール - コレクションスキーマの分析と検証
• 🩺 診断 - コレクションアクセスの診断とトラブルシューティング

インストール

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 仕様で OAuth 2.1 認証が定義されているのは、HTTP ベースのトランスポートのみです。stdio サーバーについて、仕様では OAuth の使用を 「SHOULD NOT」 とし、代わりに環境変数から認証情報を取得するよう定めています。このサーバーはそのとおりに動作します。
• Directus 12 は静的アクセストークンを完全にサポートしています。 Directus が追加した OAuth 2.1 サポート（2026 年半ば）は、組み込みのリモート MCP エンドポイントに適用されるもので、任意です。Directus 12 ではトークン認証に関する破壊的変更はありません（DIRECTUS_V12_BREAKING_CHANGES.md を参照）。
• OAuth が関係するのは、MCP サーバーを HTTP 経由でリモート公開する場合（Streamable HTTP／SSE）のみです。Claude Desktop、Claude Code、Cursor などのローカルな stdio サブプロセスとして使う場合、このサーバーに必要なのは環境変数のトークンだけです。

Directus の User Settings → Token でトークンを生成してください（本番環境では、最小権限のロールを持つ専用ユーザーを使用してください）。

Claude サブスクリプション（Max／Pro）での使用 — API キーは不要です

MCP サーバー自体は Anthropic API トークンを消費しません。消費するのは AI クライアントによるモデル呼び出しのみです。Claude Max（または Pro）サブスクリプションで Claude Code または Claude Desktop 内からこのサーバーを使用する場合、モデルの使用料はサブスクリプションに含まれるため、Anthropic API キーは不要です。API キーが必要なのは、Claude API 経由でプログラムから Claude を操作する場合（例：リモート MCP コネクター）のみです。

---

IDE の設定

🟣 Cursor

1. Cursor の設定を開きます：Cmd+,（macOS）または Ctrl+,（Windows/Linux）
2. **「MCP」**を検索するか、Features → MCP Servers に移動します
3. **「Edit in 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 Servers」**を検索します
3. **「Edit in 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 を再度開き、MCP の初期化に約 10 秒かかるので待ちます

---

🤖 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 対応 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 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 を1つのコレクション、または複数のコレクションに一度にインポートします

診断

ツール	説明
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 は、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）から読み込まれるため、シェル履歴に残りません。結果はツールごとに「成功」「インスタンスによる拒否」「失敗」として報告され、「このサーバーに問題がある」場合と「このインスタンスが拒否した」場合を区別できます。--apply-schema は merge モードで差分を適用し、追加のみの差分を生成するため、スクラッチコレクションを再作成することしかできず、既存のものを削除することはありません。前のフェーズが失敗した場合も、クリーンアップは実行されます。

E2E テストスイートでは、公式 MCP SDK クライアント（StdioClientTransport）を使用して、dist/index.js をサブプロセスとして起動し、一時ポート上のプロセス内モック Directus と通信します。実際の Directus インスタンスやネットワークアクセスは必要ありません。

---

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

---

ライセンス

MIT © Jorge Domingues Nunes

---

リンク

• npm パッケージ
• GitHub リポジトリ
• Directus ドキュメント
• MCP プロトコル仕様