@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 사양은 HTTP 기반 전송에 대해서만 OAuth 2.1 인증을 정의합니다. stdio 서버의 경우 사양은 구현체가 이를 사용해서는 *"안 된다(SHOULD NOT)"*고 명시하며, 대신 환경에서 자격 증명을 가져와야 한다고 합니다 — 이 서버가 정확히 그렇게 동작합니다.

• Directus 12는 정적 액세스 토큰을 완전히 지원합니다. Directus가 (2026년 중반에) 추가한 OAuth 2.1 지원은 자체 내장 원격(remote) MCP 엔드포인트에 적용되며 선택 사항입니다. Directus 12에는 토큰 인증에 대한 주요 변경(breaking change) 사항이 없습니다 (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 지원 웹)

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 구독과 특정 브라우저 확장 프로그램이 필요할 수 있습니다.

사용 가능한 도구

컬렉션 관리

스키마 및 필드

플로우 관리

사용자 관리

파일 관리

진단

탐색

도구 안전 주석

모든 도구에는 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 }

사용 예제

구성 후에는 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 모드로 diff를 생성하며, 이는 엄격히 추가적인 diff이므로 스크래치 컬렉션만 다시 생성할 수 있습니다 — 이미 존재하던 항목은 삭제할 수 없습니다. 이전 단계가 실패해도 정리 작업은 실행됩니다.

e2e 스위트는 공식 MCP SDK 클라이언트(StdioClientTransport)를 사용하여 dist/index.js를 하위 프로세스로 실행하고, 임시 포트에서 인프로세스 mock 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

링크

• npm 패키지

• GitHub 저장소

• Directus 문서

• MCP 프로토콜 사양