esper-mcp

An MCP (Model Context Protocol) server for the Esper MDM API. Exposes your Esper fleet as AI tools so Claude (or any MCP-compatible client) can list devices, check status, fire commands, manage groups, query telemetry, and more — directly via the Esper REST API without any espercli dependency.

---

Requirements

• Python 3.10+
• An Esper account with an API key and enterprise ID

---

Installation

Option 1 — pip editable install (development)

cd /path/to/esper-mcp
pip install -e .

Option 2 — uvx (no install required)

uvx esper-mcp

---

Configuration

Set three environment variables before starting the server:

Variable	Description	Example
ESPER_ENVIRONMENT	Your Esper environment subdomain	ncpfe
ESPER_API_KEY	Your Esper API bearer token	abc123...
ESPER_ENTERPRISE_ID	Your enterprise UUID	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

These map to the Esper base URL: https://{ESPER_ENVIRONMENT}-api.esper.cloud/api

---

Claude Desktop configuration

Add to your ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "esper": {
      "command": "uvx",
      "args": ["esper-mcp"],
      "env": {
        "ESPER_ENVIRONMENT": "your-env",
        "ESPER_API_KEY": "your-key",
        "ESPER_ENTERPRISE_ID": "your-enterprise-uuid"
      }
    }
  }
}

---

Claude Code configuration

Add to ~/.claude/claude_desktop_config.json or a .mcp.json file in your project root:

{
  "mcpServers": {
    "esper": {
      "command": "uvx",
      "args": ["esper-mcp"],
      "env": {
        "ESPER_ENVIRONMENT": "your-env",
        "ESPER_API_KEY": "your-key",
        "ESPER_ENTERPRISE_ID": "your-enterprise-uuid"
      }
    }
  }
}

If you installed with pip install -e ., replace the command/args with:

{
  "command": "esper-mcp",
  "args": []
}

---

Available tools

Devices

Tool	Description
list_devices	List fleet devices with optional filtering by state, group, or name
get_device	Get full details for a device by name or UUID
get_device_status	Get latest telemetry: battery, RAM, storage, WiFi signal
get_device_heartbeat	Check if a device is online/offline and when it was last seen
list_all_heartbeats	Fetch online/offline status for every device (parallel, sorted by recency)

Location

Tool	Description
get_device_location	Get last known GPS coordinates for a specific device
list_all_locations	Get last known location for all devices that have reported location

Commands

Tool	Description
send_device_command	Send a command to a device (REBOOT, LOCK, PING, WIPE, INSTALL, etc.)
send_group_command	Send a command to all devices in a group
get_command_status	Poll the status of a command request (SUCCESS/FAILURE/IN_PROGRESS/QUEUED)
get_device_command_history	View past commands sent to a device

Groups

Tool	Description
list_groups	List all device groups
get_group	Get details for a specific group
create_group	Create a new group, optionally nested under a parent
delete_group	Delete a group by name or UUID
list_group_devices	List all devices in a specific group
add_device_to_group	Add a device to a group
remove_device_from_group	Remove a device from a group

Applications

Tool	Description
list_apps	List apps in the enterprise catalog, with optional name filter
get_app	Get details for a specific app
list_app_versions	List all uploaded versions of an app
get_device_installs	List apps installed on a specific device

Fleet & Telemetry

Tool	Description
get_fleet_status	High-level fleet health metrics (active, at-risk, last-seen breakdown)
get_telemetry	Time-series telemetry for a device (battery, temperature, etc.)

Policies

Tool	Description
list_policies	List all device policies
get_policy	Get full details for a specific policy

Users

Tool	Description
list_users	List tenant users (system accounts filtered by default)
invite_user	Invite a new user by email with a specified role

Content

Tool	Description
list_content	List files in the enterprise content library
delete_content	Delete a file from the content library

Bug Reports

Tool	Description
list_bugreports	List bug reports for a specific device

---

Example usage with Claude

List all active devices in the fleet.

What is the battery level on device "kiosk-lobby-01"?

Reboot all devices in the "store-floor" group.

Show me all devices that haven't been seen in the last 7 days.

What apps are installed on device abc-123?

---

Architecture notes

• All API calls go directly to https://{environment}-api.esper.cloud/api using the requests library.
• list_all_heartbeats uses concurrent.futures.ThreadPoolExecutor (8 workers) to parallelize per-device heartbeat fetches.
• Every tool returns descriptive error strings on failure rather than raising, so Claude receives useful feedback when something goes wrong.
• Device lookup accepts either the human-readable alias name or the UUID, searching by name first.