@staminna/directus-mcp-server

Directus 12 向けの MCP サーバー — アイテム、コレクション、ファイル、フロー、ユーザー、スキーマツール。TypeScript で、全体が型付けされています。

テストカバレッジ

カバレッジバッジは coverage/coverage-summary.json から npm run badges によって生成されます（外部サービスは不要です）。先に npm run test:coverage を実行してください。

特徴

• 🔐 完全な認証 - Directus とのトークンベース認証

• 📦 コレクション管理 - コレクションとアイテムの CRUD 操作

• 📁 ファイル操作 - ファイルのアップロード、ダウンロード、管理

• 🔄 フロー管理 - Directus フローの作成、更新、トリガー、管理

• 👥 ユーザー管理 - ユーザーの CRUD とロール管理

• 🔍 スキーマツール - コレクションスキーマの分析と検証

• 🩺 診断 - コレクションアクセスの診断とトラブルシューティング

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

環境変数

TLS / クライアント証明書

Directus インスタンスがプライベート CA を使用している場合、またはクライアント証明書を要求する場合に設定します。CA/CERT/KEY/PFX の各変数には、ファイルパスまたは PEM/DER コンテンツそのもののいずれかを指定できます。

認証 — OAuth は不要

このサーバーは 静的 Directus アクセストークン（DIRECTUS_TOKEN）を使用し、stdio トランスポートで動作します。設計上、OAuth は不要です：

• MCP 仕様では、OAuth 2.1 認可は HTTP ベースのトランスポートに対してのみ定義されています。stdio サーバーについては、仕様では実装は "SHOULD NOT"（使用すべきではない）とされており、代わりに環境から資格情報を取得すべきとされています — このサーバーはまさにそのとおりに動作します。

• Directus 12 は静的アクセストークンを完全にサポートしています。 Directus が追加した OAuth 2.1 サポート（2026年半ば）は、Directus 自身の組み込みのリモート 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 サブスクリプションと特定のブラウザ拡張機能が必要な場合があります。

利用可能なツール

コレクション管理

スキーマとフィールド

フロー管理

ユーザー管理

ファイル管理

診断

ディスカバリー

ツールの安全性アノテーション

すべてのツールにはMCPアノテーションが付与されており、クライアントは呼び出し前に読み取りと書き込みを区別できます。内訳は、17個が readOnlyHint: true、6個が明示的に destructiveHint: false（追加型 — 作成）、11個が destructiveHint: true（削除、上書き更新、apply_schema、import_data、trigger_flow）です。

destructiveHint はMCP仕様ではデフォルトで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が実行されていることを確認: 設定した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）から読み取られるため、シェルの履歴に残ることはありません。結果はツールごとに pass / refused-by-instance / fail として報告され、「このサーバーは壊れている」と「このインスタンスが拒否した」を区別します。--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プロトコル仕様