Box Admin Analytics MCP

boxadm-mcp

English | 日本語

MCP (Model Context Protocol) server that surfaces external file flow from a Box admin's point of view. It reads Box's enterprise event log (admin_logs) to highlight "who shares a lot with the outside" and "which files get accessed from outside" — an early-warning signal for leakage, not a general-purpose file browser.

Documentation: https://shigechika.github.io/boxadm-mcp/

Read-only: it never revokes shares, deletes files, or otherwise mutates anything — it only surfaces risk. This is a different tool from a general-purpose Box file MCP (the official Box MCP, or the claude.ai Box connector): those operate on a user's own files and cannot see enterprise events, which is exactly what this server is for.

Named after the admin-console viewpoint (boxadm = Box admin), sibling of gwsadm-mcp.

Features

Auth model

Two modes, selected via BOX_AUTH_MODE:

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

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)

1. Developer Console → Create Platform App → Custom App → User Authentication (OAuth 2.0)
2. Redirect URI: http://localhost:8787/callback
3. 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)
4. Enable the app in the Admin Console (unpublished apps are disabled by default under most tenant policies)
5. Note the Client ID / Client Secret
6. 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)

Setup

# uv

uv pip install boxadm-mcp

pip

pip install boxadm-mcp

Or from source:

git clone https://github.com/shigechika/boxadm-mcp.git

cd boxadm-mcp

uv

uv sync

pip

pip install -e .

Configuration

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.

Scope and limits

• Access tools (external_access_events, and the access half of daily_brief) read the enterprise-wide events stream. Hitting max_events sets capped: true (oldest-first scan).
• Exposure (enumeration) tools only see folders visible to the co-admin account (not a guaranteed 100% of the enterprise), plus max_folders/max_depth limits (surfaced via capped). Requires the Read all files and folders scope.
• The scan fans its per-folder lookups out concurrently (BOX_SCAN_CONCURRENCY), since Box has no enterprise-wide collaboration listing — this widens how many folders finish inside a tool-call timeout, but coverage is still bounded by the caps. The read path retries 429 (honoring Retry-After) and transient 5xx with jittered backoff, so a passing throttle recovers instead of degrading coverage; a folder dropped by a per-folder API error that outlasts those retries (e.g. a persistent 403) is counted in fetch_errors: coverage is complete only when capped is false and fetch_errors is 0.
• Enumeration tools share a short-TTL scan memo across calls; public_shared_links skips collaboration calls entirely (optimization).
• `get_user` reads the enterprise user directory instead — one request, no paging, and structurally not an enumerator (it answers about the login you pass and nothing else). Its capped flag discloses a truncated search, so a found: false from a truncated result reads as inconclusive rather than negative.

DLP tracing (reverse-lookup by accessor)

To answer "what did this external account download": pass created_by_logins (comma-separated logins) to external_access_events. It keeps only that accessor's events and returns per-file detail (matched_events: item id/name, owner, size in bytes+GB, timestamp, event_type, whether it was via a share link).

external_access_events(since_hours=26, created_by_logins="someone@example.com")

• Since the accessor could appear anywhere in the window, a filtered call auto-extends the scan cap to up to 50,000 events (oldest-first) — but only matching events are kept, so memory stays bounded.
• In this mode the response carries events_matched (match count) instead of events_scanned (no running total is kept; use capped to judge coverage). capped: true means the window wasn't fully scanned — raise max_events.
• Box's admin_logs API has no created_by query parameter, so this is a client-side filter (fetch_admin_events(created_by_logins=...)).

One folder's contents (list_folder_items)

An ls, not a cat. Written for a help desk answering a submitted enquiry whose attachments land in a Box folder: instead of a human going to find that folder, the answer names the attachments and links straight to them. File content is never read, and no shared link is ever created — an existing one is reported because it is an exposure finding, not a convenience.

Who uploaded an item is not where you would look for it. For an upload made through a File Request, Box records no user at all: created_by and modified_by both read *"Anonymous User"*, and owned_by is the application's own service account — identical on every row. The only field carrying the submitter is uploader_display_name, and despite its name the value observed in practice was an email address. It is therefore matched as an opaque string (exact, case-insensitive) and never parsed or validated as an address. For a file uploaded by a signed-in user the reverse holds, so created_by is the fallback.

Ordering and time bounds are computed here rather than by Box:

• Box documents sort as the second sort attribute — items order by type first, so a subfolder precedes every file regardless of date. Measured against a real folder, sort=date also matched neither created_at nor modified_at order, so it cannot honestly be presented as "newest".
• since / until are compared as instants, not text. Box stamps items in its own UTC offset while a caller asks in theirs, so a lexicographic comparison is wrong by that difference at every date boundary and silent about it. Both bounds must carry an offset; a bare date is refused rather than guessed.

limit bounds what is RETURNED, not what is searched — a full page is fetched first, so an uploader's item is found even when it is not among the newest. Truncation is disclosed twice over, because they are different truths: returned vs matched is the caller's own limit, while capped means the folder holds more than one page and a miss is inconclusive rather than negative.

One file's text (read_file, opt-in)

The cat to list_folder_items' ls, for the same help desk: after listing an enquiry's attachments, read the one it is about. It is registered only when BOXADM_READ_FOLDER_IDS names one or more folders, and every call is refused unless Box reports the file's parent, or one of its ancestors, as one of those folders. The account behind this server can see far more than one use needs; this keeps the reader to the folders you named.

The text is Box's own extracted_text representation, so it needs only preview rights: nothing is downloaded or parsed here, and an account that may not download a file can still read it. Spreadsheets arrive as tab-separated cells, documents and PDFs as their text. A file Box has no text for (an image, an archive) returns its metadata with text: null; a file Box has not processed yet is waited for up to 20 seconds. The text is capped at max_chars (default 20000, at most 100000), with truncated saying whether it was cut.

The bearer token goes only to the configured API base and to Box's download hosts (https, a *.boxcloud.com name, a path un