PnP.PowerShell MCP Server
This guide covers the PnP.PowerShell MCP Server, which lets an MCP-compatible AI assistant run PnP.PowerShell cmdlets against SharePoint and Microsoft 365.
The server communicates over MCP stdio. It discovers cmdlets from the installed PnP.PowerShell module, provides current cmdlet documentation, validates cmdlet and parameter names, and runs each requested expression in a fresh PowerShell process.
Start here
- New users: install and connect.
- Already installed: see how to use the tools and authentication options.
- Operators: review security and confirmations.
For detailed client-specific configuration snippets, see the repository README. The repository also contains the best-practices guide, which is exposed to MCP clients as the pnp://best-practices resource.
Getting started
Requirements
-
PowerShell 7 or later (
pwsh) available inPATH. -
PnP.PowerShell installed in that PowerShell installation:
Install-Module PnP.PowerShell -Scope CurrentUser -
An Entra ID app registration configured for PnP.PowerShell and the permissions your work requires. See the PnP.PowerShell registration guide.
-
An MCP-compatible client. For building from source, install Go as specified in
go.mod.
Install the server
Download a prebuilt binary from GitHub Releases and verify it against the release checksums.txt, or build/install with Go:
git clone https://github.com/14096/pnp-powershell-mcp-server.git
cd pnp-powershell-mcp-server
make build
bin/pnp-powershell-mcp-server version
The server binary is bin/pnp-powershell-mcp-server (add .exe on Windows). Use its absolute path in your MCP client configuration. Alternatively, install the latest published version with:
go install github.com/14096/pnp-powershell-mcp-server@latest
Sign in and make a first request
For the default authentication flow, sign in once from PowerShell and persist the login so fresh PowerShell processes can reuse its token:
Connect-PnPOnline -Url "https://<tenant>.sharepoint.com" -Interactive -ClientId "<app-id>" -PersistLogin
Configure your MCP client to start the server, then restart or reload that client. Ask the assistant to verify access with pnpTestConnection, then to perform a simple read-only task, such as listing the site’s lists. A typical discovery flow is:
- Search for relevant cmdlets with
pnpSearchCmdlets. - Read current syntax with
pnpGetCmdletDocs. - Run a read-only expression with
pnpRunCmdlet.
The client setup chapter links to ready-to-use configuration examples. The first server start builds its local cmdlet catalog in the background; tools that require it wait for the catalog to be ready.
Install and connect an MCP client
The server uses stdio, so the client launches the server process directly. Configure the command as the absolute path to the downloaded or built binary, then restart/reload the MCP client.
The repository README has current configuration examples for:
- OpenCode
- Claude Code
- Cursor
- VS Code with GitHub Copilot Chat
- GitHub Copilot CLI
Client config file locations and field names can change with client versions, so check the client’s MCP documentation if an example does not match your installation. Keep stdio settings intact: do not allocate a terminal or print other output to stdout, which is reserved for MCP messages.
Check that the server starts
Run the version command to check the binary itself:
/absolute/path/to/pnp-powershell-mcp-server version
For a protocol-level check without an AI client, use the MCP Inspector:
npx @modelcontextprotocol/inspector /absolute/path/to/pnp-powershell-mcp-server
If the client cannot start the process, check that the configured path exists, is executable, and that PowerShell 7 and PnP.PowerShell are installed where the server can find them. See troubleshooting for more.
Using the tools
The server exposes these tools:
| Tool | Purpose |
|---|---|
pnpSearchCmdlets | Search installed PnP.PowerShell cmdlets by keyword, optionally filtering by verb or noun. Results include related cmdlets. |
pnpGetCmdletDocs | Fetch current documentation for a cmdlet, falling back to local Get-Help when online docs are unavailable. |
pnpRunCmdlet | Run a PowerShell expression. PnP cmdlet and parameter names are checked before execution; risky operations require confirmation. |
pnpRefreshCmdlets | Rebuild the local cmdlet catalog. Setting update: true installs the latest module first and requires confirmation. |
pnpGetModuleInfo | Report the installed PnP.PowerShell version and catalog status. |
pnpTestConnection | Connect to a site and verify access by reading its title and URL. Uses the configured --url, or accepts siteUrl with a client ID or persisted connection profile. It never returns tokens or credentials. |
When --url is not configured, call pnpTestConnection with a SharePoint siteUrl and either clientId or profile. The check uses interactive authentication and reads the site’s web title and URL; it does not modify SharePoint data.
Recommended workflow
Ask the assistant to search, read docs, then run. For example, instead of guessing syntax, have it find a suitable cmdlet with pnpSearchCmdlets, check it with pnpGetCmdletDocs, and only then call pnpRunCmdlet.
Expressions run in a fresh pwsh process and $ErrorActionPreference is set to Stop. Keep expressions focused, select only the properties needed, and convert results to JSON when structured output is useful:
Get-PnPList | Select-Object Title, Id, ItemCount | ConvertTo-Json -Depth 3
Valid JSON is compacted automatically. Large responses may be truncated; the result explains how to continue with offset, but narrowing the query with cmdlet parameters such as -First, -Query, or -Identity is usually more efficient.
Resources and prompts
- The
pnp://best-practicesresource provides the repository’s best-practices guide. - Read-only prompt starting points are
pnpAuditSitePermissions,pnpInventoryLists,pnpFindCmdlet, andpnpTeamsOverview. Clients may expose prompts as slash commands.
Tool results include structured content alongside readable text. Results have an ok flag; for example, pnpGetCmdletDocs includes markdown, source, and module version, while pnpRunCmdlet can return output, parsed JSON data, truncation status, and confirmation details.
Authentication
By default, the server does not manage sign-in. Your expressions connect using Connect-PnPOnline. Each tool call starts a new PowerShell process, so a connection object is not shared between calls; a persisted PnP.PowerShell login can be reused from the token cache.
Interactive sign-in (default)
From PowerShell 7, persist an interactive login:
Connect-PnPOnline `
-Url "https://<tenant>.sharepoint.com" `
-Interactive `
-ClientId "<app-id>" `
-PersistLogin
Then include the site URL in requests so the assistant can connect before running the relevant cmdlets. Depending on your PnP.PowerShell version and operating system, persisted-login behavior can vary. Reconnect if the token expires.
Other sign-in modes include device login, certificates, and managed identity. Choose the method that matches your environment and avoid putting secrets into assistant requests. The best-practices guide has examples.
Optional automatic connection
To connect to one site before every pnpRunCmdlet call, start the server with --url and --client-id (and optionally --tenant), or set PNP_MCP_URL, PNP_MCP_CLIENTID, and PNP_MCP_TENANT:
pnp-powershell-mcp-server \
--url "https://<tenant>.sharepoint.com" \
--client-id "<app-id>"
The URL must be HTTPS. This flow reuses a login persisted with Connect-PnPOnline -PersistLogin; it does not store credentials. If an expression supplies its own Connect-PnPOnline, the automatic connection is skipped. Connecting to a different site requires confirmation.
Optional persisted connections for multiple tenants
Pass --persisted-connections (or PNP_MCP_PERSISTED_CONNECTIONS) a JSON array with tenant names and the app client IDs used for their persisted logins. You can provide inline JSON or prefix a file path with @:
[
{ "tenant": "contoso", "clientId": "<app-id>" },
{ "name": "fabrikam-prod", "tenant": "fabrikam", "clientId": "<other-app-id>" }
]
When an expression connects to a listed tenant without specifying a client ID, the server supplies the configured client ID and interactive sign-in options. An optional name can be selected with the profile argument to pnpRunCmdlet. Use --strict-connections (or PNP_MCP_STRICT_CONNECTIONS=1) with this setting to reject connections to tenants that are not configured.
The configuration contains tenant names and app IDs, not secrets. Environment variables required for an authentication method are not passed to PowerShell by default; explicitly allow only the required names with --pass-env / PNP_MCP_PASS_ENV. See security before passing secrets.
Security and confirmations
pnpRunCmdlet runs with your operating-system user’s privileges and the permissions of the active PnP.PowerShell connection. It is not a sandbox. Use an Entra ID app with least-privilege permissions, keep client-side tool approval enabled, and avoid unattended use against production tenants.
What requires confirmation
Before execution, the server parses and checks the expression. Read-only PnP operations can run without a prompt. Risky operations are held for confirmation; examples include:
- Destructive actions such as
Remove-*,Clear-*,Reset-*, or.Delete(). - Permission changes, privilege changes, app deployment, and write operations through REST or batch methods.
- Local file or environment access, external programs, arbitrary code execution, and commands outside the recognized safe PnP and formatting commands.
- Updating PnP.PowerShell with
pnpRefreshCmdletsandupdate: true.
The complete categories and examples are maintained in the README security section.
Confirmation flow
By default, the tool returns a description of the proposed operations without executing them. The assistant must show the exact actions and obtain an explicit yes/no from you. After approval, it retries the same expression with a single-use token that expires after five minutes. A declined request never reaches PowerShell.
Some MCP clients support a native confirmation dialog. Start the server with --elicitation to request it. Client support varies; if no response is received within 45 seconds, the server falls back to conversational confirmation. Keep the client’s own tool approval enabled as an additional safeguard.
Static checks cannot catch every possible side effect. Review each requested operation and its target before approving it, especially when processing untrusted content.
Environment variables
PowerShell receives a safe subset of the server environment by default. To expose additional variables needed for authentication, set --pass-env NAME1,NAME2 or PNP_MCP_PASS_ENV. Pass only the names required; any variable exposed to PowerShell is available to expressions that run there.
Practical safeguards
- Never include passwords, client secrets, or access tokens in expressions.
- Use least-privilege app permissions and verify the target tenant/site before write operations.
- Keep token caches and user profiles access-controlled, especially on shared machines.
- Treat confirmation as a safety net, not a substitute for review or isolation.
Best practices
The repository’s detailed PnP.PowerShell MCP Server best-practices guide covers authentication examples, error handling, output formatting, common SharePoint and Teams patterns, paging, and debugging. It is also available to MCP clients as the pnp://best-practices resource.
Key recommendations:
- Search for a cmdlet and read its current documentation before running it.
- Prefer narrow queries and select only the fields needed; use JSON for structured results.
- Use persisted sign-in for interactive work and certificate or managed identity authentication for automation where appropriate.
- Never put credentials into expressions. Grant only the app permissions required for the task.
- Read confirmation details carefully, verify the target, and explicitly approve only intended operations.
- For long output, narrow the request first. If you page a result, remember that the expression is re-executed for each page.
Troubleshooting
The MCP client cannot start the server
- Verify the configured command uses the absolute path to the executable and that it is executable.
- Check that
pwshis PowerShell 7 or later and is available in the server process’sPATH. - Install PnP.PowerShell in that PowerShell environment, not only in Windows PowerShell 5.1.
- Restart/reload the MCP client after changing its configuration.
- Run
pnp-powershell-mcp-server versionand use the MCP Inspector to separate startup problems from client configuration problems.
Not connected, expired token, or access denied
Run pnpTestConnection to check access: it reports the site title and URL on success, or an actionable error otherwise. Then sign in with Connect-PnPOnline using the intended site and app registration. If using persisted login, confirm that it was created with -PersistLogin, that the client ID matches, and that the token has not expired. Access denied usually means the app or signed-in identity lacks a required permission; review the requested operation and grant only the needed permission.
Unknown cmdlet or parameter
Use pnpSearchCmdlets and pnpGetCmdletDocs to check the installed module’s available names and syntax. The local cmdlet catalog is rebuilt when the module version changes. pnpRefreshCmdlets rebuilds it on demand; update: true additionally installs a newer module and requires confirmation.
Missing or stale documentation
Cmdlet docs are fetched from the PnP.PowerShell development documentation and cached for 24 hours by module version. Cached docs can be served offline, so they may not match the currently installed module exactly. Check local Get-Help or the official documentation if syntax differs.
Output was truncated
Use the returned offset to continue, or preferably narrow the cmdlet query with options such as -First, -Identity, or -Query, and shape the result with Select-Object. The expression runs again on each page, so paging a changing dataset may produce inconsistent results.
Logs and caches
Server logs are written to stderr; stdout is reserved for the MCP protocol. The cmdlet catalog is stored under the user’s cache directory at pnp-powershell-mcp-server/catalog.json. Documentation is cached under pnp-powershell-mcp-server/docs/<module-version>/. Cache files are owner-only. Removing a cache file forces the relevant data to be rebuilt or fetched again.