ImmyBot MCP server

@wyre-ai/immybot-mcp

MCP server for ImmyBot - Windows endpoint management and software deployment automation.

Features

• 🔐 OAuth 2.0 Authentication - Microsoft Entra ID client credentials
• 🏢 Multi-tenant Support - Per-instance subdomain configuration
• 🧭 Decision Tree Navigation - Organized tool discovery by domain
• 💻 Comprehensive Coverage - Computers, software, deployments, scripts, tenants, maintenance sessions, tasks
• ⚡ Gateway Ready - Stateless per-request operation for WYRE MCP Gateway
• 🚀 Docker Deployment - Container-ready with health checks
• 📊 Structured Logging - Detailed operation tracking

Quick Start

Docker (Recommended)

docker run -d \
  --name immybot-mcp \
  -p 8080:8080 \
  -e AUTH_MODE=gateway \
  -e MCP_HTTP_PORT=8080 \
  -e LOG_LEVEL=info \
  ghcr.io/wyre-ai/immybot-mcp:latest

Direct Installation

npm install @wyre-ai/immybot-mcp
npx @wyre-ai/immybot-mcp

Navigation

The server uses decision-tree navigation to organize tools by domain:

1. Start → immybot_navigate → Choose domain
2. Domain tools → Domain-specific operations
3. Return → immybot_back → Main navigation

Available Domains

• computers - Device and endpoint management
• software - Application and package management
• deployments - Software deployment configuration
• scripts - PowerShell script execution and management
• tenants - Client organization management
• maintenancesessions** - Device maintenance and state reconciliation
• tasks - Background operation monitoring

Authentication

ImmyBot uses OAuth 2.0 with Microsoft Entra ID:

Required Configuration

Setup Steps

1. Register Enterprise Application in Microsoft Entra ID
2. Grant ImmyBot API permissions to the application
3. Create client secret for the application
4. Configure application in ImmyBot settings

OAuth scope: api://{client_id}/.default

Usage Examples

1. Navigate to Computers Domain

// Start navigation
await callTool('immybot_navigate', { domain: 'computers' });

// List computers
await callTool('immybot_computers_list', { 
  tenantId: 1,
  isOnline: true 
});

// Get computer details
await callTool('immybot_computers_get', { computerId: 123 });

2. Software Management

// Navigate to software domain
await callTool('immybot_navigate', { domain: 'software' });

// Search for software
await callTool('immybot_software_search', { query: 'Chrome' });

// Install software (stages for maintenance session)
await callTool('immybot_software_install', {
  softwareId: 456,
  computerIds: [123, 124, 125],
  autoUpdate: true
});

3. Maintenance Sessions

// Navigate to maintenance sessions
await callTool('immybot_navigate', { domain: 'maintenance_sessions' });

// Start maintenance session (reconciles deployments)
await callTool('immybot_maintenance_sessions_start', {
  computerId: 123,
  sessionType: 'Manual'
});

// Check session status
await callTool('immybot_maintenance_sessions_get', { sessionId: 789 });

Two-Step Deployment Model

⚠️ Important: ImmyBot uses a two-step deployment workflow:

1. Configure desired state - Software installations create deployments
2. Reconcile via maintenance session - Sessions apply the desired state

// Step 1: Stage software installation
await callTool('immybot_software_install', {
  softwareId: 123,
  computerIds: [456]
});
// ↑ This creates a deployment, does NOT install immediately

Shortened. The full README is on GitHub.