# Level.io RMM MCP Server

[![CI](https://github.com/pbozzay/level-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/pbozzay/level-mcp/actions/workflows/ci.yml)

An unofficial Model Context Protocol (MCP) server for [Level.io](https://level.io/), the modern remote monitoring and management (RMM) platform for IT teams and managed service providers (MSPs). Connect AI clients such as Codex or Claude Desktop to the Level v2 REST API for endpoint inventory, monitoring alerts, automations, groups, tags, custom fields, and available updates.

This community project is not affiliated with or endorsed by Level Software, Inc.

## What is Level.io?

Level.io is a remote monitoring and management platform for managing Windows, macOS, and Linux devices across IT environments. Level describes its broader RMM product around unified device management, proactive monitoring and alerting, intelligent automation, centralized patch management, remote control, scripting, and asset inventory.

This MCP server covers the operations currently available in Level's [public v2 API](https://levelapi.readme.io/reference/). It does not imply API access to every feature in the Level web application.

## Level.io MCP tools

The server generates 35 typed MCP tools from Level's published OpenAPI specification:

- **Devices and endpoint inventory:** list devices, inspect hardware and operating-system details, update device metadata, move devices between groups, and delete devices
- **Monitoring and alerting:** list alerts, inspect alert details, filter active or resolved alerts, and resolve alerts
- **RMM automations:** list automations and webhook triggers, inspect automation runs, and trigger configured automation webhooks
- **Groups:** list, create, update, and delete groups; assign devices to groups or remove them
- **Tags:** list, create, update, and delete tags; apply tags to devices or remove them
- **Custom fields:** manage custom-field definitions and values for organizations, groups, and devices
- **Available updates:** list and inspect software or operating-system updates reported by Level

Tool schemas preserve Level's required fields, enums, nullable values, pagination cursors, and webhook variables. The API key is server configuration and is never exposed as an MCP tool argument.

## Common AI-assisted RMM workflows

- Find devices or endpoints by hostname, serial number, group, or tag
- Review device inventory, operating-system, CPU, memory, disk, network, motherboard, and security data
- Triage active monitoring alerts and resolve handled alerts
- Organize endpoints with Level groups, tags, and custom fields
- Inspect available or installed updates by device, status, or category
- Discover and trigger Level automation webhooks

Mutation tools are annotated so compatible MCP clients can distinguish read-only operations from writes and destructive actions.

## Requirements

- Node.js 20 or newer
- A Level.io API key created under **Settings → API Keys** in Level

Use a read-only API key for inventory, reporting, or alert review. Use a read-and-write key only when the MCP client needs to create, update, resolve, trigger, or delete Level resources. See Level's [public API guide](https://docs.level.io/en/articles/12152745-level-public-api).

## Install locally

```sh
git clone https://github.com/pbozzay/level-mcp.git
cd level-mcp
npm ci
npm run build
```

## Configure Codex

Codex reads MCP servers from `~/.codex/config.toml`. Use the absolute path to the built `dist/index.js` file.

The simplest configuration stores the Level.io API key directly in your Codex configuration:

```toml
[mcp_servers.level]
command = "node"
args = ["C:\\absolute\\path\\to\\level-mcp\\dist\\index.js"]
startup_timeout_sec = 15
tool_timeout_sec = 60
default_tools_approval_mode = "writes"

[mcp_servers.level.env]
LEVEL_API_KEY = "your-level-api-key"
```

`config.toml` is a local user file, but this method stores the key there as plaintext. Never commit that file or the key to Git.

To keep the key out of `config.toml`, allow Codex to forward it from the environment instead:

```toml
[mcp_servers.level]
command = "node"
args = ["C:\\absolute\\path\\to\\level-mcp\\dist\\index.js"]
env_vars = ["LEVEL_API_KEY"]
default_tools_approval_mode = "writes"
```

Set `LEVEL_API_KEY` before launching Codex, then fully restart the Codex app, CLI, or IDE extension. Use `/mcp` or the **MCP servers** settings page to confirm that `level` is connected.

## Configure another MCP client

For clients that use JSON MCP configuration, use the same built entry point:

```json
{
  "mcpServers": {
    "level": {
      "command": "node",
      "args": ["C:/absolute/path/to/level-mcp/dist/index.js"],
      "env": {
        "LEVEL_API_KEY": "your-level-api-key"
      }
    }
  }
}
```

Restart the MCP client after changing its configuration. Keep configuration files containing API keys private.

## Run directly

Set `LEVEL_API_KEY` to the value Level expects in its `Authorization` header, then start the stdio server:

```sh
LEVEL_API_KEY="your-level-api-key" npm start
```

PowerShell:

```powershell
$env:LEVEL_API_KEY = "your-level-api-key"
npm start
```

## Configuration

| Environment variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `LEVEL_API_KEY` | Yes for authenticated operations | — | Value sent in the Level API `Authorization` header |
| `LEVEL_API_BASE_URL` | No | `https://api.level.io` | Alternate Level API origin for a proxy or test server |
| `LEVEL_API_TIMEOUT_MS` | No | `30000` | Per-request timeout in milliseconds |

Level automation webhooks can be configured without authorization. The server therefore permits `triggerWebhook` without `LEVEL_API_KEY`; when a key is configured, it is sent.

## Development

```sh
npm run check
npm test
npm run build
```

Refresh the checked-in Level v2 OpenAPI document whenever Level publishes API schema changes:

```sh
npm run spec:update
```

The server communicates over MCP stdio. API failures and argument-validation failures become MCP tool errors; successful JSON responses are returned as readable text and structured content.

## License and trademarks

The source code is available under the MIT License. Level, Level.io, and related product names are trademarks of their respective owners. This repository is an independent open-source integration.