Skip to main content

Install Lokka

This quick start guide will help you set up Lokka with the minimum configuration needed to get started.

If you want to learn more about the advanced configuration options, see the Advanced Install Guide.

Pre-requisites​

  • Install Node.js
    • If you already have Node v22.10 or higher installed you can skip this step.
    • Check by running node -v at the command prompt.

Configure the agent​

You can use the Lokka agent tool with any compatible MCP client and LLM combo.

Claude is the simplest way to get started and provides the best experience. You can use the free version of Claude Desktop to test Lokka (there are daily limits on the free version).

GitHub Copilot Agent in VS Code is another great option.

MCP Registry

Lokka also includes MCP Registry metadata under the registry name io.github.jozrahq/lokka. Direct npx -y @merill/lokka installs remain the most broadly compatible path, while registry-aware clients can discover Lokka once a release has been published to the MCP Registry.

Install Claude Desktop​

  • Download the latest version of Claude Desktop from https://claude.ai/download
  • Install the application by following the instructions on the website.
  • Open the application and sign in with your account (you can register for a free account).

Add Lokka to Claude Desktop​

  • In Claude Desktop, open Settings by clicking on the hamburger icon in the top left corner.
  • Select File > Settings (or press Ctrl + ,)
    • On Mac, you can find the settings in the top menu bar under Claude > Settings (or press Cmd + ,).
  • In the Developer tab, click Edit Config
    • Note: If you don't see the Developer tab, you need to enable it first from Help > Enable Developer Mode.
  • This opens explorer, edit claude_desktop_config.json in your favorite text editor.
  • Add the following configuration to the file.
{
  "mcpServers": {
    "Lokka-Microsoft": {
      "command": "npx",
      "args": ["-y", "@merill/lokka"]
    }
  }
}
  • Exit Claude Desktop and restart it.
    • Every time you make changes to the code or configuration, you need to restart Claude desktop for the changes to take effect.
    • Note: In Windows, Claude doesn't exit when you close the window, it runs in the background. You can find it in the system tray. Right-click on the icon and select Quit to exit the application completely.

Testing the agent​

  • Open the Claude Desktop application.
  • Type lokka sign in to open the connections panel and click Sign in — a browser window opens to sign into your Microsoft tenant.
    • By default Lokka remembers your sign-in (cached securely in your OS credential store), so you won't be prompted again on the next launch. Uncheck Stay signed in when signing in if you prefer a session-only connection.
  • Type lokka help to open a visual tour of everything Lokka can do — the interactive Graph explorer (open lokka), Lokka Settings (lokka settings) for connections and Guardrails, multi-tenant connections (lokka sign in), and permission management (lokka permissions). Guardrails are off by default, but you can turn them on in Settings while testing to limit model tool-call HTTP methods, API paths, or specific resources. Direct Graph Explorer runs are user-driven and are not blocked by guardrails. See the Interactive apps guide for details.
  • Now you can start quering your Microsoft tenant using the Lokka agent tool.
  • Some sample queries you can try are:
    • Get all users in my tenant
    • Show me the details for John Doe
    • Change John's department to IT - Needs User.ReadWrite.All permission to be granted
    • How many VMs do I have in my subscription? - Needs Reader permission to be granted to the Azure subscription