ninjaone-mcp

NinjaOne RMM MCP 서버 — NinjaOne의 Public API v2(Organizations, Devices, Alerts, Ticketing, Automation/Scripting, Jobs)를 MCP 도구로 노출합니다.

NinjaOne이란 무엇이며 / 에이전트가 언제 사용해야 하나

NinjaOne은 MSP가 고객의 IT 자산을 관리하는 데 사용하는 RMM(원격 모니터링 및 관리) 플랫폼입니다. 에이전트는 다음과 같은 요청에 이 MCP를 사용해야 합니다:

• "이 고객의 장치는 몇 개이며, 어떤 장치가 오프라인인가요?" → ninjaone_get_organization_devices / ninjaone_get_devices

• "이 장치/조직에 활성 알림이 있나요?" → ninjaone_get_device_alerts / ninjaone_get_alerts

• "지원 보드에 열린 티켓은 무엇인가요?" → ninjaone_get_ticket_boards 그 다음 ninjaone_get_tickets

• "이 장치에서 디스크 정리를 실행하고 완료되면 알려주세요" → ninjaone_get_device_scripting_options로 실행 가능한 항목 확인, ninjaone_run_script_on_device, 그 다음 ninjaone_get_device_active_jobs로 완료 확인

• "사용 가능한 자동화 스크립트는 무엇인가요?" → ninjaone_get_automation_scripts

개요

이 서버는 Model Context Protocol(Streamable HTTP 전송)을 구현하며, MSPbots Vendor MCP Service SOP에 따라 23개 도구를 5개 그룹으로 제공합니다: 무상태(stateless), 자격 증명 미저장, 요청별 헤더 인증.

이 프로젝트는 커뮤니티 wyre-technology/ninjaone-mcp 프로젝트의 도구 표면(organizations/devices/alerts/tickets, 여기서는 Node SDK 대신 NinjaOne의 REST API를 직접 호출하도록 재구현)에서 시작하여, NinjaOne 자체 OpenAPI 3.0.1 스펙에서 가져온 5개의 automation/scripting/jobs 도구로 확장했습니다 — 아래의 모든 엔드포인트는 실제 NinjaOne API 스펙과 대조하여 검증했으며, 추측하거나 2차 소스에서 복사하지 않았습니다.

NinjaOne은 OAuth2 client_credentials로 인증합니다: NinjaOne "API Services" OAuth2 앱의 client ID + secret을 POST {base_url}/oauth/token에서 단기 bearer 토큰으로 교환합니다. 이 서버는 모든 도구 호출 시마다 이 교환을 직접 수행하며, 호출 간에 토큰(또는 client_id/secret)을 저장하거나 캐시하지 않습니다.

빠른 시작

Docker(권장)

docker compose up --build

서버는 http://localhost:8080에서 시작됩니다.

로컬(uv)

uv sync
python -m ninjaone_mcp

상태 확인

curl http://localhost:8080/health
# {"status": "ok"}

상태 확인 엔드포인트에는 자격 증명이 필요 없습니다.

인증 매개변수 설명 (Authentication)

/mcp에 대한 모든 요청에는 다음 HTTP 헤더가 포함되어야 합니다:

필수 헤더 중 하나라도 없으면 401 Unauthorized를 반환합니다.

환경 변수

base-URL 환경 변수는 없습니다. base URL은 X-Ninja-Region 헤더에서 요청별로 파생됩니다(config.py의 지역 표 참조).

MCP 엔드포인트

POST http://localhost:8080/mcp

MCP 클라이언트를 다음으로 연결하세요:

• 전송: http(Streamable HTTP)

• 헤더: X-Ninja-Client-Id, X-Ninja-Client-Secret(둘 다 필수), X-Ninja-Region(선택)

도구 목록

테스트 예시 (Test Example)

티켓 보드 나열:

{
  "method": "tools/call",
  "params": { "name": "ninjaone_get_ticket_boards", "arguments": {} }
}

실행 중인 서버에 대한 동일한 curl(streamable HTTP MCP 엔드포인트):

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "X-Ninja-Client-Id: <client_id>" \
  -H "X-Ninja-Client-Secret: <client_secret>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "ninjaone_get_ticket_boards", "arguments": {} }
  }'

장치에서 스크립트 실행:

{
  "method": "tools/call",
  "params": {
    "name": "ninjaone_run_script_on_device",
    "arguments": { "device_id": 123, "type": "SCRIPT", "script_id": 456 }
  }
}

API 참조

• 문서: https://app.ninjarmm.com/apidocs-beta/core-resources(eu/oc/ca/us2/fed에 대한 지역별 동일 문서)

• 인증: POST /oauth/token에서 OAuth2 client_credentials 그랜트(grant_type, client_id, client_secret, scope), 범위: monitoring, management, control

알려진 격차 / 구현 참고 사항

• 엔드포인트 출처 검증: 자동화/스크립팅/작업 관련 5개 엔드포인트(requestScriptingOptions, runScriptOnDevice, getActiveJobs, getDeviceActiveJobs) 중 4개는 독립적으로 확보한 NinjaOne의 OpenAPI 스펙 사본과 대조 검증을 거쳤습니다. getAutomationScripts는 해당 사본에 존재하지 않았으며(해당 스펙 개정판보다 최신임), 정확한 /api 경로 배치는 나머지 4개의 확인된 패턴에서 추론된 것이지 독립적으로 검증된 것이 아닙니다. tools/automation.py 상단의 주석을 참조하세요.

• ninjaone_get_tickets의 클라이언트 측 필터링: NinjaOne의 보드 실행 엔드포인트 요청 스키마는 filters/searchCriteria 파라미터를 정의하지만, 커뮤니티 wyre-technology 프로젝트에 따르면 실제로는 400 오류가 발생합니다. 따라서 이 도구는 항상 필터링되지 않은 페이지를 요청하고 status/organization_id/device_id 필터링을 대신 클라이언트 측에서 수행합니다.

• 단일 티켓 조회 또는 독립형 댓글 추가 엔드포인트 없음: NinjaOne의 티켓팅 API는 GET /ticketing/ticket/{id}를 제공하지 않으므로, 단일 티켓을 조회하려면 해당 보드에서 ninjaone_get_tickets를 페이지 단위로 탐색해야 합니다. 댓글 추가도 별도 엔드포인트가 아니라 ninjaone_update_ticket의 comment/comment_public 파라미터에 통합되어 있으며, 티켓 자체에 대한 PUT과 함께 수행됩니다.

• ninjaone_get_devices의 df 필터는 조직 범위로 지정할 때 NinjaOne에 의해 조용히 무시될 수 있음(커뮤니티 프로젝트에서 알려진 문제) — 조직 범위의 장치 목록에는 ninjaone_get_organization_devices를 사용하는 것이 좋습니다.

• 실제 자격 증명을 사용한 실시간 NinjaOne 계정 테스트는 아직 수행되지 않음 — 현재까지 검증된 사항: tools/list가 23개 도구 모두를 깔끔한 스키마로 반환하고, pytest(15개 테스트)가 통과하며, 더미 client_id/secret으로 실시간 호출 시 NinjaOne의 실제 프로덕션 /oauth/token 엔드포인트에 도달하여 잘못된 형식의 요청 오류가 아닌 실제로 잘 구성된 거부 응답(Client app not exist)을 받았습니다. 이를 통해 기본 URL, 토큰 엔드포인트, 요청 형식이 올바르다는 것이 확인되었습니다.