Lokka is a model-context-protocol server for the Microsoft Graph and Azure RM APIs that allows you to query and manage your Azure and Microsoft 365 tenants with AI.
Please see Lokka.dev for how to use Lokka with your favorite AI model and chat client.
Lokka lets you use Claude Desktop, or any MCP Client, to use natural language to accomplish things in your Azure and Microsoft 365 tenant through the Microsoft APIs.
e.g.:
Create a new security group called 'Sales and HR' with a dynamic rule based on the department attribute.
Find all the conditional access policies that haven't excluded the emergency access account
Show me all the Intune device configuration policies assigned to the 'Call center' group
What was the most expensive service in Azure last month?
Lokka now supports multiple authentication methods to accommodate different deployment scenarios:
For user-based authentication with interactive login, you can use the following configuration:
This is the simplest config and uses the default Lokka app.
{
"mcpServers": {
"Lokka-Microsoft": {
"command": "npx",
"args": ["-y", "@merill/lokka"]
}
}
}
If you wish to use a custom Microsoft Entra app, you can create a new app registration in Microsoft Entra and configure it with the following environment variables:
{
"mcpServers": {
"Lokka-Microsoft": {
"command": "npx",
"args": ["-y", "@merill/lokka"],
"env": {
"TENANT_ID": "<tenant-id>",
"CLIENT_ID": "<client-id>",
"USE_INTERACTIVE": "true"
}
}
}
}
Traditional app-only authentication. You can use either certificate (recommended) or client secret authentication with the following configuration.
See Install Guide for more details on how to create an Entra app.
App only authentication using a PEM-encoded client certificate:
{
"mcpServers": {
"Lokka-Microsoft": {
"command": "npx",
"args": ["-y", "@merill/lokka"],
"env": {
"TENANT_ID": "<tenant-id>",
"CLIENT_ID": "<client-id>",
"CERTIFICATE_PATH": "/path/to/certificate.pem",
"CERTIFICATE_PASSWORD": "<optional-certificate-password>",
"USE_CERTIFICATE": "true"
}
}
}
}
For comfort, in order to convert a PFX client certificate to a PEM-encoded certificate:
openssl pkcs12 -in /path/to/cert.pfx -out /path/to/cert.pem -nodes -clcerts
{
"mcpServers": {
"Lokka-Microsoft": {
"command": "npx",
"args": ["-y", "@merill/lokka"],
"env": {
"TENANT_ID": "<tenant-id>",
"CLIENT_ID": "<client-id>",
"CLIENT_SECRET": "<client-secret>"
}
}
}
}
Token-based authentication where the MCP Client provides access tokens:
{
"mcpServers": {
"Lokka-Microsoft": {
"command": "npx",
"args": ["-y", "@merill/lokka"],
"env": {
"USE_CLIENT_TOKEN": "true"
}
}
}
}
When using client-provided token mode:
- Start the MCP server with
USE_CLIENT_TOKEN=true
- Use the
set-access-token
tool to provide a valid Microsoft Graph access token - Use the
get-auth-status
tool to verify authentication status - Refresh tokens as needed using
set-access-token
set-access-token
: Set or update access tokens for Microsoft Graph authenticationget-auth-status
: Check current authentication status and capabilitiesadd-graph-permission
: Request additional Microsoft Graph permission scopes interactively
Lokka now supports controlling the default Microsoft Graph API version used for all requests:
- Default behavior: Uses
beta
version for access to latest features - Production mode: Set
USE_GRAPH_BETA=false
to force all requests to usev1.0
version - Per-request override: You can still specify
graphApiVersion
parameter in individual requests (unlessUSE_GRAPH_BETA=false
)
When USE_GRAPH_BETA=false
, all Graph API calls will use the stable v1.0
version, even if beta
is explicitly requested in the graphApiVersion
parameter.
See the docs for more information on how to install and configure Lokka.
-
Lokka-Microsoft
- Call Microsoft Graph & Azure APIs. Supports querying Azure and Microsoft 365 tenants. Updates are also supported if permissions are provided.
- Input:
apiType
(string): Type of Microsoft API to query. Options: 'graph' for Microsoft Graph (Entra) or 'azure' for Azure Resource Management.path
(string): The Azure or Graph API URL path to call (e.g. '/users', '/groups', '/subscriptions').method
(string): HTTP method to use (e.g., get, post, put, patch, delete)apiVersion
(string): Azure Resource Management API version (required for apiType Azure)subscriptionId
(string): Azure Subscription ID (for Azure Resource Management).queryParams
(string): Array of query parameters like $filter, $select, etc. All parameters are strings.body
(JSON): The request body (for POST, PUT, PATCH)
- Returns: Results from the Azure or Graph API call.
-
set-access-token
(New in v0.2.0)- Set or update an access token for Microsoft Graph authentication when using client-provided token mode.
- Input:
accessToken
(string): The access token obtained from Microsoft Graph authenticationexpiresOn
(string, optional): Token expiration time in ISO format
- Returns: Confirmation of token update
-
get-auth-status
(New in v0.2.0)- Check the current authentication status and mode of the MCP Server
- Returns: Authentication mode, readiness status, and capabilities
The configuration of the server is done using environment variables. The following environment variables are supported:
Name | Description | Required |
---|---|---|
TENANT_ID |
The ID of the Microsoft Entra tenant. | Yes (except for client-provided token mode) |
CLIENT_ID |
The ID of the application registered in Microsoft Entra. | Yes (except for client-provided token mode) |
CLIENT_SECRET |
The client secret of the application registered in Microsoft Entra. | Yes (for client credentials mode only) |
USE_INTERACTIVE |
Set to "carview.php?tsp=true" to enable interactive authentication mode. | No |
USE_CLIENT_TOKEN |
Set to "carview.php?tsp=true" to enable client-provided token authentication mode. | No |
USE_CERTIFICATE |
Set to "carview.php?tsp=true" to enable certificate authentication mode. | No |
CERTIFICATE_PATH |
Path to the PEM-encoded certificate file for certificate authentication. | Yes (for certificate mode only) |
CERTIFICATE_PASSWORD |
Password for the certificate file (if encrypted). | No |
REDIRECT_URI |
Redirect URI for interactive authentication (default: https://localhost:3000 ). |
No |
ACCESS_TOKEN |
Initial access token for client-provided token mode. | No |
USE_GRAPH_BETA |
Set to "false" to force all Graph API calls to use v1.0 instead of beta (default: true, allows beta). | No |
- Interactive and Token-based Authentication (v0.2.0) - @darrenjrobinson
- Certificate Authentication (v0.2.1) - @nitzpo
To use this server with the Claude Desktop app, add the following configuration to the "mcpServers" section of your
claude_desktop_config.json
:
{
"mcpServers": {
"Lokka-Microsoft": {
"command": "npx",
"args": ["-y", "@merill/lokka"]
}
}
}
{
"mcpServers": {
"Lokka-Microsoft": {
"command": "npx",
"args": ["-y", "@merill/lokka"],
"env": {
"TENANT_ID": "<tenant-id>",
"CLIENT_ID": "<client-id>",
"CLIENT_SECRET": "<client-secret>"
}
}
}
}
Make sure to replace <tenant-id>
, <client-id>
, and <client-secret>
with the actual values from your Microsoft Entra application. (See Install Guide for more details on how to create an Entra app and configure the agent.)