Setup¶

Install¶

uv pip install boxadm-mcp
# or
pip install boxadm-mcp

From source:

git clone https://github.com/shigechika/boxadm-mcp.git
cd boxadm-mcp
uv sync          # or: pip install -e .

Auth model¶

Two modes, selected via BOX_AUTH_MODE:

ccg (default) — Client Credentials Grant, server-to-server. Simpler to run unattended if your Box tenant has an available server-authentication app slot.
oauth — OAuth 2.0 user auth. An admin authorizes once in a browser; the refresh token keeps it running unattended after that.

admin_logs (enterprise events) is readable in either mode, provided the authorizing/impersonated user is an admin and the app has the Manage enterprise properties scope.

OAuth setup (one-time, by a Box admin)¶

Developer Console → Create Platform App → Custom App → User Authentication (OAuth 2.0)
Redirect URI: http://localhost:8787/callback
Application Scopes: check Manage enterprise properties (required for admin_logs). Add Read all files and folders too if you also want collaboration/share-link enumeration, and Manage users if you want the get_user lookup (each scope change requires re-consent via boxadm-mcp auth)
Enable the app in the Admin Console (unpublished apps are disabled by default under most tenant policies)
Note the Client ID / Client Secret
First login: set BOX_AUTH_MODE=oauth etc., then run boxadm-mcp auth → authorize in the browser → a token cache is written to ~/.config/boxadm-mcp/token.json (chmod 600)

ccg mode needs no browser and no local token cache

If your tenant has a server-authentication app slot available, ccg mode reads only plain string secrets (BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID) and never touches BOX_TOKEN_CACHE — nothing to provision per machine.

Environment variables¶

Variable	Description	Default
`BOX_AUTH_MODE`	`oauth` / `ccg`. Any other value falls back to `ccg`; `health_check` reports the mode in effect	`ccg`
`BOX_CLIENT_ID`	App Client ID	required
`BOX_CLIENT_SECRET`	App Client Secret	required
`BOX_ENTERPRISE_ID`	Enterprise ID (CCG subject; not needed for oauth)	required in ccg mode
`BOX_OAUTH_REDIRECT_URI`	oauth redirect	`http://localhost:8787/callback`
`BOX_TOKEN_CACHE`	oauth token cache path (file path; only touched in oauth mode, self-generated by `boxadm-mcp auth`)	`~/.config/boxadm-mcp/token.json`
`BOX_API_BASE`	Box API base URL	`https://api.box.com`
`BOX_SCAN_CONCURRENCY`	Parallel per-folder lookups in the enumeration scan	`8` (clamped 1–32)
`BOX_SCAN_DEADLINE`	Soft wall-clock budget (seconds) for one enumeration scan; `0`/negative disables. When hit, the scan returns a disclosed partial (`capped=true`)	`45`
`BOX_HTTP_TIMEOUT`	Per-request HTTP timeout (seconds)	`30`
`BOX_ALLOWED_DOMAINS`	Internal email domains, comma-separated. No default — every address counts as external until set	required

Keep secrets out of .mcp.json (e.g. in a local env file sourced before launch); .mcp.json itself can reference ${BOX_CLIENT_ID}-style variables and be safely committed.

Register with an MCP client¶

Claude Code (plugin)¶

This repository doubles as a single-plugin marketplace:

/plugin marketplace add shigechika/boxadm-mcp
/plugin install boxadm-mcp@boxadm-mcp

The plugin launches uvx boxadm-mcp and reads the same environment variables as every other transport; export BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID, and BOX_ALLOWED_DOMAINS before starting Claude Code. The plugin ships with BOX_AUTH_MODE=ccg by default — switch to oauth only after running boxadm-mcp auth once yourself, since the plugin cannot provision that browser step or the resulting token cache file for you.

uvx must be on the PATH of the process that runs Claude Code — a login shell usually has it, but a GUI-launched app may not; install uv system-wide if the plugin fails to start.

Claude Code (manual)¶

.mcp.json:

{
  "mcpServers": {
    "boxadm-mcp": {
      "type": "stdio",
      "command": "boxadm-mcp",
      "env": {
        "BOX_AUTH_MODE": "oauth",
        "BOX_CLIENT_ID": "${BOX_CLIENT_ID:-}",
        "BOX_CLIENT_SECRET": "${BOX_CLIENT_SECRET:-}",
        "BOX_ALLOWED_DOMAINS": "example.com"
      }
    }
  }
}

CLI¶

boxadm-mcp auth       # OAuth first-time login (opens a browser)
boxadm-mcp --version  # Print version and exit
boxadm-mcp            # Start MCP server (STDIO, default)

No-argument mode is the normal one — that is how MCP clients launch it.

Next¶

Reference covers every tool, scope and limits, DLP tracing, and get_user's exact-match rules.