CIPP

CIPP MCP Server

MCP (Model Context Protocol) server for CIPP — the CyberDrain Improved Partner Portal. Provides AI assistants with structured access to CIPP's M365 multi-tenant management capabilities.

Features

• 49 tools across 12 categories
• Tenant, user, group, and mailbox management
• Mailbox and online-archive size reporting, per tenant or per user
• Per-user Entra ID sign-in logs (status, location, Conditional Access, MFA)
• Security: Conditional Access policies, named locations, Microsoft Secure Score
• Standards & compliance: BPA, domain health, drift detection
• License reporting (per-tenant and CSP-wide)
• Alerts, audit logs, and scheduled tasks
• GDAP role and invite management
• Stdio and HTTP transport modes
• MCP Gateway compatible

Prerequisites

• Node.js 18+
• A running CIPP deployment
• CIPP API Key (generated from CIPP Settings → API Client Management)

Installation

Via npm (once published)

npx cipp-mcp

From source

git clone https://github.com/WYRE-AI/cipp-mcp

cd cipp-mcp npm install npm run build

Configuration

Set these environment variables (or copy .env.example to .env):

[!IMPORTANT]

CIPP_BASE_URL must be the Azure Function App URL — the CIPP-API backend,

https:// .azurewebsites.net — not the Static Web App /

custom-domain UI URL (e.g. https://cipp.yourdomain.com). The SWA's built-in

auth intercepts bearer tokens and redirects them to its interactive login page,

so every API call fails. Find the Function App (named like cippXXXXX) in your

CIPP resource group in the Azure Portal.

/health stays unauthenticated and does not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.

HTTP authentication

With MCP_TRANSPORT=http and CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S. The header value is t= ,v1= , where v1 is the hex-encoded HMAC-SHA256 of the ASCII string t= keyed with CONDUIT_S2S_SECRET. The timestamp must be within 300 seconds of the server clock. A missing or invalid header is HTTP 401, before CIPP credentials are read. The secret is never written to logs.

X-Gateway-S2S: t=1710000000,v1=<64 lowercase hex chars>

In AUTH_MODE=gateway, /mcp also requires x-base-url plus either x-api-key or all of x-tenant-id, x-client-id, and x-client-secret (x-token-scope, x-token-url, and x-token-scope-fallback are optional). Those headers are the only CIPP credential source for that request. A request missing them is HTTP 401 and does not use CIPP_* from the process environment.

AUTH_MODE=env still requires a valid X-Gateway-S2S header, then uses CIPP_* from the environment.

Local HTTP without a secret is development-only. It binds 127.0.0.1 even when MCP_HTTP_HOST is 0.0.0.0 or another non-loopback address:

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run dev

Docker

The image listens on 0.0.0.0 inside the container (MCP_HTTP_HOST) and defaults to AUTH_MODE=gateway. Publish the port on loopback and pass the same S2S secret the gateway uses. In gateway mode, CIPP credentials arrive on each request as headers; they are not read from the environment.

docker build -t cipp-mcp .

docker run --rm \ -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \ -p 127.0.0.1:8080:8080 \ cipp-mcp

Compose refuses to start when CONDUIT_S2S_SECRET is unset. The cipp-mcp service is gateway mode: it sets AUTH_MODE=gateway, publishes 127.0.0.1:8080:8080, and does not set CIPP_API_KEY, CIPP_CLIENT_ID, CIPP_CLIENT_SECRET, CIPP_TENANT_ID, CIPP_BASE_URL, or env_file.

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

Single-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses CIPP_*:

docker run --rm \

-e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \ -e AUTH_MODE=env \ -e CIPP_BASE_URL=https://cippXXXXX.azurewebsites.net \ -e CIPP_TENANT_ID=your-entra-tenant-id \ -e CIPP_CLIENT_ID=your-client-id \ -e CIPP_CLIENT_SECRET=your-client-secret \ -p 127.0.0.1:8080:8080 \ cipp-mcp

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{

"mcpServers": { "cipp": { "command": "node", "args": ["/path/to/cipp-mcp/dist/entry.js"], "env": { "CIPP_BASE_URL": "https://cippXXXXX.azurewebsites.net", "CIPP_TENANT_ID": "your-entra-tenant-id", "CIPP_CLIENT_ID": "your-client-id", "CIPP_CLIENT_SECRET": "your-client-secret" } } } }

Note: CIPP_BASE_URL must be the Azure Function App URL (.azurewebsites.net), not

the frontend SWA URL (.azurestaticapps.net or your custom domain). The SWA enforces

browser-based auth and will redirect all API requests to a Microsoft login page.

Tools

Editing a user right after creating it

edit_user first resolves the account's current UPN, because CIPP's Invoke-EditUser rebuilds the UPN from username + Domain on every call and editing without it would rename the account. Graph can lag a few seconds behind a just-created account, so when that lookup finds nothing, answers HTTP 404, or fails with a 5xx whose body is Graph's not-found (the Request_ResourceNotFound code, or Graph's "Resource ' ' does not exist or one of its queried reference-property objects are not present" message), it is retried up to 4 attempts in total, waiting 1s, 3s and 6s (~10s). The decision uses the HTTP status, not message text; any other 4xx (400, 401, 403) and other 5xx are not retried. If the user still isn't visible the error says "Tried N times" and, when the last attempt got an HTTP error, its status; wait a moment and retry.

Mailbox and archive sizes

list_mailbox_usage reports every mailbox in a tenant — primary size, item count, quota, percent of quota, and the same four figures for the online archive — sorted largest first, with tenant-wide totals that cover every mailbox even when only the top rows are returned.

It requires CIPP's reporting database to have been synced for that tenant. This is not a design choice: Invoke-ListMailboxes' live Exchange query selects no size fields at all, so the cache is the only tenant-wide source of sizes. Sync it from CIPP under Reports → Report Settings. If it has not been synced the tool says so and names the remedy rather than returning an empty result.

get_mailbox_usage reports the same figures for a single mailbox and reads live, so it needs no cache. Prefer it when the cache is unavailable or stale.

Two caveats worth knowing:

• Concealed report names blank the tenant-wide sizes. With *Reports: conceal user, group, and site names* enabled in the Microsoft 365 admin centre, Graph's usage report returns 32-character hashes instead of UPNs, so CIPP's join against the mailbox list matches nothing and every mailbox caches a size of 0 — a tenant that reads as empty rather than as failed. list_mailbox_usage detects this and returns a warning alongside the totals. get_mailbox_usage is unaffected: it reads the Exchange admin API directly.
• Sizes are gigabyte-rounded on the per-user path. CIPP rounds to two decimal places of a gigabyte before returning, so get_mailbox_usage byte counts are accurate to roughly 10 MB. Quotas are exact — they are recovered from the raw Get-Mailbox string, which carries the true byte count.

User sign-in logs

list_user_signin_logs returns one user's most recent interactive sign-ins, newest first: time, app, IP, location, success or failure with error code and reason, client app, Conditional Access status and the policies that evaluated, the authentication methods Graph recorded (first factor included — whether MFA was required is authenticationRequirement), device, and risk when flagged — plus a summary of failures, distinct IPs and countries.

• Accepts a UPN or an object id, and always resolves it first. CIPP filters Graph on userId, which is the Entra object id; a UPN there matches nothing and returns an empty page that reads as "this user never signs in". An unresolvable user is an error, not an empty result.
• One tenant, one user, one page. top defa