@merill/lokka

Lokka

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.

Have ideas or feature requests? Share feedback and vote on requests at lokka.userjot.com. Bugs and code discussions still belong in GitHub Issues.

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?

Authentication Methods

Lokka now supports multiple authentication methods to accommodate different deployment scenarios:

Interactive Auth

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"]
    }
  }
}

Interactive auth with custom app

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"
      }
    }
  }
}

App-Only Auth

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 Auth with Certificate

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

#### App-Only Auth with Client Secret

{
  "mcpServers": {
    "Lokka-Microsoft": {
      "command": "npx",
      "args": ["-y", "@merill/lokka"],
      "env": {
        "TENANT_ID": "<tenant-id>",
        "CLIENT_ID": "<client-id>",
        "CLIENT_SECRET": "<client-secret>"
      }
    }
  }
}

Client-Provided Token

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

New Tools

Token Management Tools

• set-access-token: Set or update access tokens for Microsoft Graph authentication
• get-auth-status: Check current authentication status and capabilities
• add-graph-permission: Request additional Microsoft Graph permission scopes interactively

Graph API Version Control

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 use v1.0 version
• Per-request override: You can still specify graphApiVersion parameter in individual requests (unless USE_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.

Getting started

See the docs for more information on how to install and configure Lokka.

• Introduction
• Install guide
• Developer guide

Components

Tools

• 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 authentication
    • expiresOn (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

Environment Variables

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 "true" to enable interactive authentication mode.	No
USE_CLIENT_TOKEN	Set to "true" to enable client-provided token authentication mode.	No
USE_CERTIFICATE	Set to "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: http://localhost:3200).	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
LOKKA_DISABLE_TOKEN_CACHE	Set to "true" to disable the secure OS token cache — connections are then never remembered across restarts.	No
LOKKA_CONFIG_DIR	Directory for Lokka's saved-connection metadata (default: ~/.lokka). Contains no tokens or secrets.	No
LOKKA_DISABLE_TELEMETRY	Set to "true" to disable anonymous usage telemetry. (DO_NOT_TRACK=1 is also honored, and telemetry is off automatically when CI is set.)	No

Telemetry

Lokka sends a single anonymous "server started" event to PostHog each time it launches, to help gauge how widely it's used. It is anonymous and contains no personal or tenant data — only a random per-install id, the Lokka version, the authentication mode (e.g. interactive — never any credentials), and coarse environment info (OS, architecture, Node version). No tenant ids, usernames, tokens, secrets, client ids, or file paths are ever collected, and no PostHog person profile is created.

To opt out, set either LOKKA_DISABLE_TELEMETRY=true or DO_NOT_TRACK=1. Telemetry is also skipped automatically in CI (when CI is set).

Contributors

• Interactive and Token-based Authentication (v0.2.0) - @darrenjrobinson
• Certificate Authentication (v0.2.1) - @nitzpo

Interactive apps

In hosts that support MCP Apps (like Claude Desktop and VS Code with GitHub Copilot), Lokka ships six interactive apps that render right inside the chat. Type lokka help for a visual tour — it's the best place to start. Other entry points: open lokka (Graph explorer with endpoint + OData IntelliSense, table/JSON results, fetch-all, code snippets, exports and a fix-your-403 permissions tab), lokka settings (Connections + Guardrails in one view), lokka sign in (multi-tenant connections — user or service principal, Global + US Gov clouds, one-click or AI-driven switching), lokka permissions (search 1,100+ Graph permissions and consent in one flow), and lokka guardrails (optional local limits for model tool-call methods, paths, and resources; off by default and useful during testing; direct Graph Explorer runs are not blocked). Full guide: lokka.dev/docs/apps.

Installation

To use this server with the Claude Desktop app, add the following configuration to the "mcpServers" section of your claude_desktop_config.json:

Interactive Authentication

{
  "mcpServers": {
    "Lokka-Microsoft": {
      "command": "npx",
      "args": ["-y", "@merill/lokka"]
    }
  }
}

Client Credentials Authentication

{
  "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.)