trmm-mcp

읽기 전용 MCP 서버로, Tactical RMM 인스턴스를 에이전트 도구로 노출하여 LLM이 장치, 클라이언트 및 감사 데이터를 수집할 수 있게 합니다 — 아무것도 변경할 수 있는 능력 없이 말이죠.

• 설계상 읽기 전용. run-script, run-command, reboot, install, edit, create 또는 delete 도구는 구현되어 있지 않습니다. API 키가 쓰기 권한이 있더라도 폭발 반경(blast radius)은 0입니다. 그래도 읽기 전용 서비스 사용자와 함께 사용하세요(심층 방어).

• Python + FastMCP. 하나의 코드베이스에서 두 가지 전송 방식을 제공합니다: MCP 클라이언트에서 로컬로 사용하는 stdio와, 팀 전체가 연결하는 공유 원격 서버를 위한 Streamable HTTP(공유 bearer-token 인증 포함) — 원격 배포를 참조하세요.

• 구성은 환경 변수 전용입니다 — 코드에 비밀 정보가 없습니다. 필수 변수가 없으면 시작 시 즉시 실패합니다.

도구

모든 도구는 readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true이고, 출력 스키마가 있는 구조화된 콘텐츠를 반환하며, 해당되는 경우 페이지네이션을 지원합니다.

정확한 엔드포인트와 감사 로그 페이로드는 docs/API_CONTRACT.md를 참조하세요.

Related MCP server: KVMFleet MCP Server

구성

TRMM에서 API 키를 받으세요: Settings → Global Settings → API Keys(읽기 전용 서비스 사용자를 선택). 이 키는 2FA를 우회하고 해당 사용자의 역할 권한을 상속합니다.

설치

Python 3.10+가 필요합니다.

cd tactical-rmm-mcp
python -m venv .venv
# Windows:  .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt

(또는 pip install -e .로 trmm-mcp 콘솔 스크립트를 얻을 수 있습니다.)

실행

서버는 stdio를 통해 MCP를 사용하므로 일반적으로 MCP 클라이언트에 의해 실행됩니다. 직접 실행하려면(stdin에서 MCP 클라이언트를 기다립니다):

# set env first, then:
python -m trmm_mcp
# or
python server.py

TRMM_API_URL/TRMM_API_KEY가 없으면 stderr에 명확한 오류를 출력하고 0이 아닌 종료 코드로 종료합니다.

MCP 클라이언트에 등록(stdio)

Claude Code — 프로젝트 .mcp.json

프로젝트에 .mcp.json을 생성하세요(종속성이 해결되도록 server.py의 절대 경로와 venv의 Python을 사용):

{
  "mcpServers": {
    "trmm": {
      "command": "C:\\Users\\admin\\your-workspace\\tactical-rmm-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\admin\\your-workspace\\tactical-rmm-mcp\\server.py"],
      "env": {
        "TRMM_API_URL": "https://api.yourdomain.com",
        "TRMM_API_KEY": "your-readonly-key",
        "TRMM_MON_TOKEN": "optional-mon-token"
      }
    }
  }
}

Claude Desktop — claude_desktop_config.json

동일한 형식으로, 최상위 "mcpServers" 키 아래에:

{
  "mcpServers": {
    "trmm": {
      "command": "/abs/path/tactical-rmm-mcp/.venv/bin/python",
      "args": ["/abs/path/tactical-rmm-mcp/server.py"],
      "env": {
        "TRMM_API_URL": "https://api.yourdomain.com",
        "TRMM_API_KEY": "your-readonly-key"
      }
    }
  }
}

macOS에서 이 파일은 ~/Library/Application Support/Claude/claude_desktop_config.json에 있습니다. Windows에서는 %APPDATA%\Claude\claude_desktop_config.json에 있습니다. 편집 후 앱을 다시 시작하세요.

원격 배포(팀 액세스)

trmm-mcp를 공유 HTTPS 서버로 실행하여 엔지니어/헬프데스크가 각자 로컬에 설치하는 대신 Claude 커넥터로 사용하게 하세요. TRMM API 키는 서버 측에 유지됩니다. 클라이언트는 공유 bearer token으로 인증합니다.

1. bearer token 생성 및 구성

python -c "import secrets; print(secrets.token_urlsafe(32))"

.env(또는 Portainer 스택 환경)에서:

TRMM_API_URL=https://api.yourdomain.com
TRMM_API_KEY=<read-only service-user key>
TRMM_MCP_TRANSPORT=http
TRMM_MCP_AUTH_TOKEN=<the token you just generated>

서버는 TRMM_MCP_AUTH_TOKEN 없이 http 모드로 시작을 거부합니다.

2. Docker / Portainer로 배포

docker compose up -d --build
curl http://localhost:8080/healthz        # -> {"status":"ok",...}

Portainer에서 이 저장소의 스택을 배포하고 스택에 환경 변수를 설정하세요 — 기존의 build → push → Portainer-webhook 재배포 흐름에 맞습니다. 이미지는 비루트 사용자로 실행되며 /healthz에 대한 Docker HEALTHCHECK를 포함합니다.

3. HTTPS + 네트워크 게이트 뒤에 배치

컨테이너 앞에서 TLS를 종료하고 액세스를 게이트하세요 — VPN 또는 Cloudflare Access 뒤에서 예: https://trmm-mcp.example.com을 제공하는 리버스 프록시(Caddy/Nginx/Traefik). bearer token은 심층 방어일 뿐 유일한 계층이 아닙니다. 인증 없이 포트 8080을 인터넷에 노출하지 마세요.

4. Claude 연결(Claude Code / Desktop)

원격 .mcp.json — 동료의 머신에 Python, 저장소 또는 TRMM 키가 필요 없습니다:

{
  "mcpServers": {
    "trmm": {
      "type": "http",
      "url": "https://trmm-mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer <shared-token>" }
    }
  }
}

claude.ai 웹 및 모바일

웹/모바일 사용자 지정 커넥터 UI는 정적 헤더가 아닌 OAuth로 인증합니다 — 따라서 위의 bearer 설정은 Claude Code + Desktop을 대상으로 합니다. 웹 + 모바일의 경우 서버 앞에 Cloudflare Tunnel + MCP Server Portal을 배치하세요: Claude 방향으로 OAuth/SSO(Entra) 흐름을 실행하고 업스트림에 bearer token을 주입하므로 추가 서버 코드가 필요 없습니다. 전체 가이드: docs/REMOTE_OAUTH_CLOUDFLARE.md. docker-compose.cloudflare.yml을 사용합니다(터널 사이드카, 게시된 포트 없음).

엔드포인트

MCP Inspector로 테스트

npx @modelcontextprotocol/inspector \
  -e TRMM_API_URL=https://api.yourdomain.com \
  -e TRMM_API_KEY=your-readonly-key \
  -- python server.py

그런 다음 Inspector UI에서: 도구를 나열하고, trmm_list_clients를 호출하고, within_days: 7로 trmm_search_audit_log를 시도하여 페이지네이션과 감사 로그 필터가 실시간 데이터에서 작동하는지 확인하세요.

평가

evaluation.xml에는 검증된 답변이 포함된 10개의 읽기 전용 MSP 질문이 있습니다. mcp-builder 스킬에 번들된 하네스로 실행하세요:

python scripts/evaluation.py \
  -t stdio -c python -a server.py \
  -e TRMM_API_URL=https://api.yourdomain.com \
  -e TRMM_API_KEY=your-readonly-key \
  -o evaluation_report.md \
  evaluation.xml

evaluation.xml의 답변은 검증된 인스턴스에 특화되어 있습니다. 다른 데이터셋에서는 다시 생성하세요.

보안 참고 사항

• 비밀 정보는 환경 변수에서만 가져옵니다. stdout에는 아무것도 기록되지 않습니다(stdio 서버는 stdout을 깨끗하게 유지해야 합니다 — 진단은 stderr로 전달됩니다).

• 오류는 인증(401) vs. 권한(403) vs. 찾을 수 없음(404) vs. 네트워크/시간 초과를 구분하는 조치 가능한 메시지로 변환되며, 내부 정보를 유출하지 않습니다.

• 이 서버는 변경(mutating) 엔드포인트를 호출하지 않습니다. 향후 명시적으로 게이트된 액션 서버는 별도의 프로젝트가 될 것입니다.