NinjaOne MCP 서버

NinjaOne와 상호작용하기 위한 Model Context Protocol (MCP) 서버로, 효율적인 도구 로딩을 위한 의사 결정 트리 아키텍처를 갖추고 있습니다.

원클릭 배포

[!IMPORTANT] 클릭하기 전에: 이 서버는 GitHub Packages npm 레지스트리에 호스팅된 @wyre-technology/node-ninjaone에 의존합니다. GitHub Packages는 익명 액세스를 지원하지 않습니다. 패키지가 공개되어 있어도 모든 npm install에는 토큰이 필요합니다. 클라우드 빌더가 npm install을 대신 실행하므로 토큰을 제공해야 하며, 그렇지 않으면 npm error 401 Unauthorized ... npm.pkg.github.com 오류로 빌드가 실패합니다.

1. read:packages 범위로 GitHub Personal Access Token을 생성합니다 (클래식 토큰). 모든 GitHub 계정으로 가능합니다. wyre-technology 조직의 구성원이 아니어도 공개 패키지를 읽을 수 있습니다.

2. 배포 흐름에서 요청할 때 빌드 변수로 추가합니다:

   • Cloudflare Workers → **NODE_AUTH_TOKEN**이라는 빌드 변수를 PAT로 설정합니다 (Workers → Settings → Build → Variables and Secrets).

   • DigitalOcean App Platform → Build Time 범위의 **GITHUB_TOKEN**이라는 암호화된 환경 변수를 PAT로 설정합니다 (.do/app.yaml에 이미 선언되어 있습니다).

[!NOTE] 두 대상 모두 전체 MCP 서버를 실행합니다. DigitalOcean은 Docker 이미지를 빌드하고 HTTP로 제공합니다. Cloudflare Workers는 SDK의 Web Standard Streamable HTTP 전송(src/worker.ts)을 통해 동일한 서버를 제공합니다. 배포 후 NinjaOne 자격 증명을 시크릿으로 설정하세요 — NINJAONE_CLIENT_ID, NINJAONE_CLIENT_SECRET, 선택적으로 NINJAONE_REGION — 또는 AUTH_MODE=gateway를 설정하여 X-Ninja-* 헤더에서 요청별로 자격 증명을 가져올 수 있습니다. MCP 엔드포인트는 /mcp이고, /health는 인증되지 않은 활성 프로브입니다.

아키텍처

이 MCP 서버는 모든 도구를 처음부터 노출하는 대신 계층적 도구 로딩 접근 방식을 사용합니다:

1. 탐색 단계: 처음에는 탐색 도구(ninjaone_navigate)만 노출합니다

2. 도메인 선택: 사용자가 도메인(장치, 조직, 알림, 티켓)을 선택합니다

3. 도메인 도구: 선택 후 서버가 도메인별 도구를 노출합니다

4. 지연 로딩: 도메인 핸들러와 NinjaOne 클라이언트는 요청 시 로드됩니다

이 아키텍처는 다음을 제공합니다:

• 인지 부하 감소 (선택할 도구 수 감소)

• 더 빠른 초기 로드 시간

• 관련 작업의 더 나은 구성

• 명확한 탐색 상태

설치

이 패키지는 GitHub Packages npm 레지스트리에 게시되며, 공개 패키지에도 토큰이 필요합니다. 한 번 인증한 후 설치하세요:

# Authenticate npm to GitHub Packages (token needs the read:packages scope)
export NODE_AUTH_TOKEN=$(gh auth token)   # or a PAT with read:packages

npm install @wyre-technology/ninjaone-mcp

저장소의 .npmrc는 이미 @wyre-technology 범위를 GitHub Packages로 지정하고 NODE_AUTH_TOKEN에서 토큰을 읽으므로 추가 구성이 필요 없습니다. 아래의 npx @wyre-technology/ninjaone-mcp에도 동일하게 적용됩니다. 설정이 필요 없는 옵션을 선호하시나요? 사전 빌드된 컨테이너 이미지(ghcr.io/wyre-technology/ninjaone-mcp) 또는 각 릴리스에 첨부된 .mcpb 번들을 사용하세요.

구성

다음 환경 변수를 설정하세요:

NinjaOne API 지역

사용법

독립 실행

# Set credentials
export NINJAONE_CLIENT_ID="your-client-id"
export NINJAONE_CLIENT_SECRET="your-client-secret"
export NINJAONE_REGION="us"

# Run the server
npx @wyre-technology/ninjaone-mcp

Claude Desktop 구성

Claude Desktop의 claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "ninjaone": {
      "command": "npx",
      "args": ["@wyre-technology/ninjaone-mcp"],
      "env": {
        "NINJAONE_CLIENT_ID": "your-client-id",
        "NINJAONE_CLIENT_SECRET": "your-client-secret",
        "NINJAONE_REGION": "us"
      }
    }
  }
}

Docker

docker build -t ninjaone-mcp .
docker run -e NINJAONE_CLIENT_ID=xxx -e NINJAONE_CLIENT_SECRET=xxx -e NINJAONE_REGION=us ninjaone-mcp

사용 가능한 도메인

장치

엔드포인트를 관리하고, 장치를 재부팅하고, 서비스와 알림을 확인합니다.

도구:

• ninjaone_devices_list - 장치 목록을 표시하며, 조직, 장치 클래스, 온라인 상태로 필터링할 수 있습니다. 페이지네이션: 전체 페이지는 hasMore: true와 다음 페이지에 전달할 cursor를 반환합니다.

• ninjaone_devices_get - 장치 세부 정보 가져오기

• ninjaone_devices_reboot - 장치 재부팅 예약

• ninjaone_devices_services - 장치의 Windows 서비스 목록 표시

• ninjaone_devices_alerts - 장치별 알림 가져오기

• ninjaone_devices_activities - 장치 활동 로그 보기

조직

고객 조직과 해당 리소스를 관리합니다.

도구:

• ninjaone_organizations_list - 조직 목록 표시

• ninjaone_organizations_get - 조직 세부 정보 가져오기

• ninjaone_organizations_create - 새 조직 생성

• ninjaone_organizations_locations - 조직 위치 목록 표시

• ninjaone_organizations_devices - 조직의 장치 목록 표시

알림

모든 장치의 알림을 보고 관리합니다.

도구:

• ninjaone_alerts_list - 필터로 알림 목록 표시

• ninjaone_alerts_get - UID로 단일 알림 가져오기 (MCP Apps 호스트에서 대화형 카드로 렌더링됨)

• ninjaone_alerts_reset - 단일 알림 재설정/해제

• ninjaone_alerts_reset_all - 장치 또는 조직의 모든 알림 재설정

• ninjaone_alerts_summary - 알림 수 요약 가져오기

기능:

• 대화형 알림 카드 (MCP Apps, SEP-1865): ninjaone_alerts_get은 MCP Apps 호스트(Claude Desktop/web)에서 대화형 카드로 렌더링되며, ninjaone_alerts_reset을 통한 카드 내 "알림 재설정" 왕복을 지원합니다. 기본적으로 중립적이며, window.__BRAND__ 주입 또는 MCP_BRAND_* 환경 변수로 브랜딩할 수 있습니다. 다른 호스트에서는 일반 JSON 동작이 변경되지 않습니다.

티켓

서비스 티켓을 관리합니다.

도구:

• ninjaone_tickets_list - 보드에서 티켓 목록 표시 (board_id 필요, status/organization_id/device_id 필터는 클라이언트 측에서 적용됩니다. 아래 참고 사항 참조)

• ninjaone_tickets_get - 티켓 세부 정보 가져오기

• ninjaone_tickets_create - 새 티켓 생성

• ninjaone_tickets_update - 기존 티켓 업데이트

• ninjaone_tickets_add_comment - 티켓에 댓글 추가

• ninjaone_tickets_comments - 티켓 댓글 가져오기

• ninjaone_tickets_boards_list - 티켓 보드 목록 표시 (board_id 값 확인용)

참고: NinjaOne은 보드별로 티켓을 조회하며, 보드 ID는 테넌트마다 다릅니다. 보드 1이 항상 "모든 티켓" 보드는 아니므로, ninjaone_tickets_list는 조용히 추측하는 대신 명시적인 board_id를 요구합니다. ninjaone_tickets_boards_list로 ID를 확인하세요. 해당 엔드포인트가 404를 반환하는 테넌트에서는 NinjaOne 웹 UI의 보드 링크 URL에서 숫자 ID를 읽으세요 (예: "모든 티켓" 사이드바 링크).

참고: NinjaOne의 보드 실행 API는 서버 측에서 상태, 조직 또는 장치별로 티켓을 필터링할 수 없습니다 (시도하면 일반적인 Bad request 오류가 발생합니다). 따라서 ninjaone_tickets_list는 이러한 필터를 하나의 보드 페이지 내에서 클라이언트 측에 적용합니다. 응답은 count(이 페이지의 일치 항목)와 scanned(검사된 티켓)을 분리하고 hasMore/cursor를 포함합니다. hasMore가 false가 될 때까지 페이지를 넘겨 모든 일치 항목을 얻으세요. 단일 페이지의 count를 보드 전체 합계로 취급하지 마세요. 상태는 각 티켓의 상태 표시 이름과 일치하므로 사용자 정의 보드 상태는 OPEN/IN_PROGRESS/WAITING/CLOSED 값에 매핑되지 않을 수 있습니다.

마찬가지로 ninjaone_devices_list는 NinjaOne의 전용 조직별 엔드포인트를 통해 organization_id로 필터링합니다 (일반 df=org 장치 필터는 신뢰할 수 없으며 조용히 전체 장치를 반환할 수 있습니다).

탐색 도구

항상 사용 가능:

• ninjaone_navigate - 작업할 도메인 선택

• ninjaone_status - 현재 상태 및 자격 증명 상태 표시

• ninjaone_back - 메인 메뉴로 돌아가기 (도메인에 있을 때)

예제 워크플로

User: Check my devices
Claude: [calls ninjaone_navigate with domain="devices"]
       -> Navigated to devices domain. Available tools: ...

User: List all Windows servers
Claude: [calls ninjaone_devices_list with device_class="WINDOWS_SERVER"]
       -> [device list results]

User: Now show me alerts
Claude: [calls ninjaone_back]
       -> Navigated back to main menu.
       [calls ninjaone_navigate with domain="alerts"]
       -> Navigated to alerts domain.

인증

NinjaOne은 인증에 OAuth 2.0을 사용합니다. 다음을 수행해야 합니다:

1. NinjaOne 대시보드에 로그인합니다

2. 관리 > 앱 > API로 이동합니다

3. 새 API 애플리케이션을 생성합니다 (애플리케이션 플랫폼: API Services, 권한 부여 유형: Client Credentials)

4. 필요한 범위를 부여합니다 — 아래 참조

5. 클라이언트 ID와 클라이언트 시크릿을 기록합니다

6. 환경 변수를 구성합니다

클라이언트 라이브러리는 토큰 갱신을 자동으로 처리합니다.

OAuth 범위

기본적으로 서버는 monitoring management를 요청합니다. 실제로 필요한 범위는 사용하는 기능에 따라 다릅니다:

API 앱에 기본값보다 적은 범위가 부여된 경우 NINJAONE_SCOPES를 일치하도록 설정하세요. NinjaOne은 앱에 부여되지 않은 범위를 요청하는 토큰 요청을 거부합니다. 권한을 좁히는 대신 400 invalid_scope를 반환하므로 토큰 교환 시 실패하며 모든 도구 호출이 읽기 포함 실패합니다. 모니터링 전용 앱의 경우:

export NINJAONE_SCOPES="monitoring"

값은 쉼표 또는 공백으로 구분할 수 있으며 대소문자를 구분하지 않습니다. 게이트웨이 배포에서는 X-Ninja-Scopes 헤더를 통해 요청별로 동일한 값을 제공할 수 있습니다.

라이선스

Apache-2.0