jamf-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

A Claude Desktop MCP (Model Context Protocol) server providing a natural-language interface for three Jamf products:

• Jamf Pro — macOS/iOS/tvOS device management
• Jamf Protect — endpoint security and threat detection
• Jamf Security Cloud — device risk management (RISK API)

Commands

# Install dependencies
uv sync

# Run the server (stdio, for Claude Desktop)
uv run jamf-mcp

# Run with environment file
uv run --env-file .env jamf-mcp

# Install in development mode
uv pip install -e .

# Test a tool directly (set env vars first)
python -c "
import asyncio, os
os.environ['JAMF_PRO_URL'] = 'https://yourorg.jamfcloud.com'
# ... set other vars
from jamf_mcp.tools.setup import register
from mcp.server.fastmcp import FastMCP
mcp = FastMCP('test')
register(mcp)
"

API Documentation

• Jamf Pro: https://developer.jamf.com/jamf-pro/docs/jamf-pro-api-overview
• Jamf Protect: https://learn.jamf.com/r/en-US/jamf-protect-documentation/Jamf_Protect_API
• Jamf Security Cloud RISK API: https://developer.jamf.com/jamf-security/docs/risk-api-2

Architecture

src/jamf_mcp/
├── server.py          # FastMCP server factory — registers all tools
├── config.py          # Env-var-backed config dataclasses (one per product)
├── response.py        # ok()/err()/not_configured() helpers + ensure_list()
├── api/
│   ├── pro.py         # Jamf Pro client — OAuth2/Basic, XML+JSON, token cache
│   ├── protect.py     # Jamf Protect GraphQL client + token cache
│   └── security.py    # Jamf Security Cloud REST client + token cache
└── tools/
    ├── setup.py       # jamf_get_setup_status, jamf_configure_help (always on)
    ├── pro/           # 37 Jamf Pro tools
    └── protect/       # 6 Jamf Protect tools
    └── security/      # 2 Jamf Security Cloud tools

Tool Registration

server.py creates the FastMCP instance and calls register(mcp) from each tool module. Each tool module exports a single register(mcp: FastMCP) -> None function that decorates its tools with @mcp.tool().