Directus MCP 서버

Directus CMS를 위한 모델 컨텍스트 프로토콜(MCP)을 구현하는 Node.js 서버입니다. AI 클라이언트가 모델 컨텍스트 프로토콜(MCP)을 통해 Directus API와 상호작용할 수 있도록 합니다.

ℹ 사전 요구 사항

• Node.js

• NPM

• Directus 인스턴스

Related MCP server: Node Omnibus MCP Server

▶️ 빠른 시작

1. Directus API 자격 증명 가져오기

   • Directus 인스턴스로 이동합니다.

   • 정적 액세스 토큰을 생성하거나 이메일과 비밀번호를 확인합니다.

   • 이 자격 증명을 안전하게 보관하세요.

2. AI 에디터에 추가

   {
     "mcpServers": {
       "directus": {
         "command": "npx",
         "args": ["-y", "@pixelsock/directus-mcp@latest"],
         "env": {
           "DIRECTUS_URL": "https://your-directus-instance.com",
           "DIRECTUS_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN"
         }
       }
     }
   }

   또는 이메일/비밀번호 인증을 사용할 수 있습니다:

   {
     "mcpServers": {
       "directus": {
         "command": "npx",
         "args": ["-y", "@pixelsock/directus-mcp@latest"],
         "env": {
           "DIRECTUS_URL": "https://your-directus-instance.com",
           "DIRECTUS_EMAIL": "your-email@example.com",
           "DIRECTUS_PASSWORD": "your-password"
         }
       }
     }
   }

   Cursor의 경우:

   1. 설정(Settings) → Cursor 설정(Cursor Settings) → MCP로 이동합니다.

   2. + Add New Global MCP Server를 클릭합니다.

   3. 구성을 붙여넣습니다.

   4. 자리 표시자 값을 Directus 자격 증명으로 바꿉니다.

   5. 저장하고 Cursor를 재시작합니다.

   Claude Desktop의 경우:

   1. 설정(Settings) → 개발자(Developer)를 엽니다.

   2. Edit Config를 클릭합니다.

   3. 코드 에디터에서 claude_desktop_config.json을 열고 구성을 붙여넣습니다.

   4. 자리 표시자 값을 Directus 자격 증명으로 바꿉니다.

   5. 저장하고 Claude를 재시작합니다.

❓ 문제 해결

Cursor나 Claude Desktop과 같은 MCP 클라이언트에서 서버를 시작하는 데 문제가 있는 경우 다음을 시도해 보세요.

유효한 Directus 자격 증명이 있는지 확인

1. Directus URL이 올바르고 액세스 가능한지 확인합니다.

2. 액세스 토큰 또는 이메일/비밀번호 자격 증명이 유효한지 확인합니다.

3. MCP 클라이언트 구성에서 자격 증명을 교체합니다.

4. MCP 클라이언트를 저장하고 재시작합니다.

Node와 NPM이 설치되어 있는지 확인

• Node.js

• NPM

다음 명령어를 실행하여 Node와 NPM이 설치되어 있는지 확인합니다:

node -v
npm -v

NPM 캐시 지우기

때때로 NPM 캐시를 지우면 npx 관련 문제가 해결될 수 있습니다.

npm cache clean --force

🛠️ 사용 가능한 도구

컬렉션 및 항목

getItems                // Get items from a collection
getItem                 // Get a single item from a collection by ID
createItem              // Create a new item in a collection
updateItem              // Update an existing item in a collection
deleteItem              // Delete an item from a collection
getCollections          // Get all collection schemas
getFields               // Get fields for a collection
getRelations            // Get relations for a collection

파일

getFiles                // Get files from Directus
uploadFile              // Upload a file to Directus

사용자 및 권한

login                   // Login to Directus and get an access token
getUsers                // Get users from Directus
getCurrentUser          // Get the current user info
getRoles                // Get roles from Directus
getPermissions          // Get permissions from Directus

시스템

getSystemInfo           // Get system information from Directus
getActivity             // Get activity logs from Directus
getConfig               // Get current configuration information

🚧 개발 모드

개발 모드에서 서버를 실행하려면:

1. 복제 및 설치:

   git clone https://github.com/pixelsock/directus-mcp.git
   cd directus-mcp
   npm install

2. .env 파일에 자격 증명 추가:

   # .env
   DIRECTUS_URL=https://your-directus-instance.com
   DIRECTUS_ACCESS_TOKEN=your_token_here
   # Or use email/password
   DIRECTUS_EMAIL=your-email@example.com
   DIRECTUS_PASSWORD=your-password

3. 개발 서버 시작:

   npm run dev

🌐 HTTP 전송 (다중 사용자 / 원격 배포)

기본적으로 서버는 stdio 전송을 사용하며, 이는 단일 사용자 로컬 AI 에디터(Cursor, Claude Desktop 등)에 이상적입니다.

다중 사용자 또는 원격 환경의 경우 MCP_TRANSPORT 환경 변수를 설정하여 Streamable HTTP 전송으로 전환할 수 있습니다.

구성

환경 변수를 설정하는 대신 CLI 인수로 --transport=http를 전달할 수도 있습니다.

HTTP 서버 실행

# Via environment variable
MCP_TRANSPORT=http MCP_PORT=3000 MCP_HOST=0.0.0.0 node dist/index.js

# Via CLI argument
node dist/index.js --transport=http

Docker 예시

docker run -p 3000:3000 \
  -e DIRECTUS_URL=https://your-directus-instance.com \
  -e DIRECTUS_ACCESS_TOKEN=your_token_here \
  -e MCP_TRANSPORT=http \
  -e MCP_HOST=0.0.0.0 \
  ghcr.io/pixelsock/directus-mcp

HTTP 서버에 MCP 클라이언트 연결

서버가 실행되면 MCP 클라이언트를 다음 주소에 연결하도록 구성합니다:

http://<host>:<port>/mcp

예를 들어 Streamable HTTP 전송을 지원하는 클라이언트의 경우:

{
  "mcpServers": {
    "directus": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

📄 Directus 개발자 리소스

• Directus API 문서

• Directus API 엔드포인트

• Directus JavaScript SDK