merill/lokka

What is Lokka?

Lokka is a small server that speaks a model‑context‑protocol (MCP) and acts as a bridge between an AI chat client (e.g., Claude Desktop) and Microsoft’s cloud APIs – the Microsoft Graph and Azure Resource Management (RM) APIs. In practice you can type natural‑language commands like “Create a security group called ‘Sales and HR’” or “What was the most expensive Azure service last month?” and Lokka translates those requests into the appropriate Graph or Azure REST calls, returning the results to the chat client.

---

How does it work?

1. Authentication – Lokka supports several ways to obtain a Microsoft access token:
   • Interactive login (user‑interactive OAuth flow) – the simplest, using the default Lokka app or a custom Entra app you register.
   • App‑only (client‑credentials) auth – using either a client secret or a PEM‑encoded certificate.
   • Client‑provided token – you supply a pre‑acquired Graph token via the set-access-token tool.
2. MCP Server – You start Lokka via npx @merill/lokka (often configured in the mcpServers section of a Claude Desktop config). The server listens on stdin/stdout and follows the MCP specification.
3. Tool calls – The AI model invokes Lokka’s built‑in tools:
   • Lokka‑Microsoft – generic wrapper for Graph or Azure RM calls (you specify apiType, path, HTTP method, etc.).
   • set-access-token – updates the token when you’re in client‑provided‑token mode.
   • get-auth-status – reports which auth mode is active and whether the server is ready.
4. Graph version control – By default Lokka uses the Graph beta endpoint (giving access to the newest features). Setting USE_GRAPH_BETA=false forces all calls to the stable v1.0 endpoint.

---

Who is it for?

• IT administrators who want to automate Azure or Microsoft 365 management through conversational AI.
• Developers building custom AI assistants that need to interact with Microsoft cloud services without writing raw HTTP code.
• Power users of Claude Desktop (or any MCP‑compatible client) who prefer natural‑language commands over the Azure portal or Graph Explorer.

---

Getting started (quick steps)

1. Install – No permanent install needed; run npx -y @merill/lokka.
2. Configure authentication – Add a block to your claude_desktop_config.json under mcpServers:

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

   (Swap CLIENT_SECRET for certificate variables or set USE_INTERACTIVE=true for interactive login.)
3. Add Lokka to Claude Desktop – The MCP client will automatically discover the Lokka‑Microsoft tool.
4. Ask questions – In the chat window, type natural‑language requests; Claude (or another model) will call the Lokka‑Microsoft tool behind the scenes and present the results.

---

Key features

• Multi‑mode authentication (interactive, certificate, client secret, token‑injection).
• Unified tool (Lokka‑Microsoft) that can query or modify both Graph and Azure RM resources.
• Beta/Production Graph toggle (USE_GRAPH_BETA).
• Token management utilities (set-access-token, get-auth-status).
• One‑click VS Code install for Windows/macOS/Linux via badge links.

---

Where to learn more?

• Documentation site: https://lokka.dev – full install guide, developer reference, and example prompts.
• GitHub repo: https://github.com/merill/lokka – stars, issues, and contribution guidelines.
• Sponsor page: if you find Lokka useful, you can support the author on GitHub Sponsors.

---

TL;DR

Lokka is a lightweight, npm‑run server that lets AI chat tools speak directly to Microsoft Graph and Azure APIs. By handling authentication and exposing a simple MCP‑compatible tool, it turns natural‑language commands into real cloud‑management actions, making Azure and Microsoft 365 administration conversational and script‑free.