How do I install ImmyBot?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does ImmyBot need an API key?

The publisher lists these environment variables: IMMYBOT_TENANT_ID, IMMYBOT_CLIENT_ID, IMMYBOT_CLIENT_SECRET, IMMYBOT_INSTANCE_SUBDOMAIN, MCP_TRANSPORT, AUTH_MODE, LOG_LEVEL.

What transport does ImmyBot use?

ImmyBot runs locally over stdio.

When was ImmyBot last checked?

Last checked 2026-11-09. MCP server for ImmyBot — Windows software deployment, maintenance, tenants, deployments.

ImmyBot MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

docker run -i --rm ghcr.io/wyre-ai/immybot-mcp:v1.2.14

Credentials from the publisher

IMMYBOT_TENANT_ID — ImmyBot Azure AD tenant ID
IMMYBOT_CLIENT_ID — ImmyBot OAuth client ID
IMMYBOT_CLIENT_SECRET — ImmyBot OAuth client secret
IMMYBOT_INSTANCE_SUBDOMAIN — ImmyBot instance subdomain (e.g. 'acme' for acme.immy.bot)
MCP_TRANSPORT — Transport mode for the server. Set to 'stdio' for local CLI use; the image defaults to 'http' for gateway hosting.
AUTH_MODE — Credential source: 'env' reads vars locally, 'gateway' expects header injection from the WYRE MCP Gateway.
LOG_LEVEL — Log verbosity: debug, info, warn, error

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1IMMYBOT_TENANT_ID=<value> IMMYBOT_CLIENT_ID=<value> IMMYBOT_CLIENT_SECRET=<secret> IMMYBOT_INSTANCE_SUBDOMAIN=<value> MCP_TRANSPORT=<value> AUTH_MODE=<value> LOG_LEVEL=<value> claude mcp add io.github.wyre-ai-immybot-mcp -- docker run -i --rm ghcr.io/wyre-ai/immybot-mcp:v1.2.14

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.wyre-ai-immybot-mcp": {4      "command": "docker",5      "args": [6        "run",7        "-i",8        "--rm",9        "ghcr.io/wyre-ai/immybot-mcp:v1.2.14"10      ],11      "env": {12        "IMMYBOT_TENANT_ID": "<value>",13        "IMMYBOT_CLIENT_ID": "<value>",14        "IMMYBOT_CLIENT_SECRET": "<secret>",15        "IMMYBOT_INSTANCE_SUBDOMAIN": "<value>",16        "MCP_TRANSPORT": "<value>",17        "AUTH_MODE": "<value>",18        "LOG_LEVEL": "<value>"19      }20    }21  }22}

claude_desktop_config.json

Local · ociPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

@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)

The image listens on 0.0.0.0 inside the container and defaults to AUTH_MODE=gateway. Publish the port on loopback and pass a real CONDUIT_S2S_SECRET. In gateway mode, ImmyBot credentials arrive on each request as headers; they are not read from the environment.

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

Compose refuses to start when CONDUIT_S2S_SECRET is unset. The gateway service does not set IMMYBOT_* variables or env_file, so a project .env cannot inject static vendor credentials. It publishes 127.0.0.1:8080:8080:

# openssl rand -hex 32 — do not use a placeholder such as changeme
CONDUIT_S2S_SECRET="$(openssl rand -hex 32)" docker compose up

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:

Start → immybot_navigate → Choose domain
Domain tools → Domain-specific operations
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
maintenance_sessions - Device maintenance and state reconciliation
tasks - Background operation monitoring

Authentication

ImmyBot uses OAuth 2.0 with Microsoft Entra ID:

Required Configuration

Field	Description	Example
`instanceSubdomain`	ImmyBot instance subdomain	`acmemsp`
`tenantId`	Microsoft Entra tenant ID	`12345678-1234-1234-1234-123456789abc`
`clientId`	Application (client) ID	`87654321-4321-4321-4321-cba987654321`
`clientSecret`	Client secret value	`your-client-secret`

Setup Steps

Register Enterprise Application in Microsoft Entra ID
Grant ImmyBot API permissions to the application
Create client secret for the application
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:

Configure desired state - Software installations create deployments
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

// Step 2: Reconcile state
await callTool('immybot_maintenance_sessions_start', {
  computerId: 456
});
// ↑ This runs the maintenance session to actually install software

Environment Variables

Copy .env.example and set the variables below.

Gateway Mode (Docker)

Variable	Default	Description
`AUTH_MODE`	`direct`	Set to `gateway` for WYRE MCP Gateway. Gateway mode requires the four `x-immybot-` credential headers on each `/mcp` request and never falls back to `IMMYBOT_`. The Docker image and Compose default to `gateway`.
`MCP_TRANSPORT`	`stdio`	Transport mode (`http` or `stdio`)
`MCP_HTTP_PORT`	`8080`	HTTP server port
`MCP_HTTP_HOST`	`0.0.0.0` when a real `CONDUIT_S2S_SECRET` is set and this is unset; `127.0.0.1` for the insecure-dev bypass	Bind address. A configured secret honors this value, including `0.0.0.0`, so container deploys stay reachable. The image and Compose set `0.0.0.0`.
`CONDUIT_S2S_SECRET`	—	Required for HTTP. HMAC secret checked against `X-Gateway-S2S` on `/mcp`. Generate with `openssl rand -hex 32`. If empty or a known placeholder, the HTTP server logs an error and exits non-zero. The value is never logged.
`MCP_ALLOW_INSECURE_DEV`	unset	Set to exactly `1` to start HTTP without `CONDUIT_S2S_SECRET`. Logs a warning, does not enforce `X-Gateway-S2S`, and binds `127.0.0.1` only. A non-loopback `MCP_HTTP_HOST` refuses to start. A placeholder secret still refuses to start. Local development only.
`LOG_LEVEL`	`info`	Logging level (`debug`, `info`, `warn`, `error`)

/health stays unauthenticated and does not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.

Direct Mode (CLI)

Variable	Required	Description
`IMMYBOT_INSTANCE_SUBDOMAIN`	✅	ImmyBot instance subdomain
`IMMYBOT_TENANT_ID`	✅	Microsoft Entra tenant ID
`IMMYBOT_CLIENT_ID`	✅	Application client ID
`IMMYBOT_CLIENT_SECRET`	✅	Client secret

HTTP authentication

With MCP_TRANSPORT=http and CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S. The check is verifyS2sHeader in src/s2s-verify.ts: the header value is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of the literal string t=<unix seconds> keyed with CONDUIT_S2S_SECRET (64 lowercase hex characters). The timestamp must be within 300 seconds of the server clock. A missing or invalid header is HTTP 401, before vendor credentials are read.

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H 'X-ImmyBot-Instance-Subdomain: acmemsp' \
  -H 'X-ImmyBot-Tenant-Id: 12345678-1234-1234-1234-123456789abc' \
  -H 'X-ImmyBot-Client-Id: 87654321-4321-4321-4321-cba987654321' \
  -H 'X-ImmyBot-Client-Secret: your-client-secret' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

In AUTH_MODE=gateway, those four X-ImmyBot-* headers are required. A request missing any of them gets HTTP 401 and does not fall back to IMMYBOT_* in the process environment. Direct mode (AUTH_MODE unset) still requires a valid X-Gateway-S2S header, then uses the IMMYBOT_* environment variables. Direct mode does not read the X-ImmyBot-* headers.

Local HTTP without a secret is development-only. It binds 127.0.0.1 and logs a warning. A non-loopback MCP_HTTP_HOST (including the image default 0.0.0.0) makes startup exit. Do not publish that port off loopback.

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

Tools Reference

Navigation Tools

Tool	Description
`immybot_navigate`	Navigate to domain
`immybot_status`	Show current state
`immybot_back`	Return to main menu

Computers Tools

Tool	Description
`immybot_computers_list`	List computers with filtering
`immybot_computers_get`	Get computer details
`immybot_computers_search`	Search computers by name
`immybot_computers_inventory`	Get hardware/software inventory
`immybot_computers_create`	Create computer record
`immybot_computers_deployments`	List computer deployments
`immybot_computers_trigger_checkin`	Force agent check-in

Software Tools

Tool	Description
`immybot_software_list_global`	List global software packages
`immybot_software_list`	List all software (global + tenant)
`immybot_software_get`	Get software details
`immybot_software_search`	Search software by name
`immybot_software_versions`	List software versions
`immybot_software_latest_version`	Get latest version
`immybot_software_categories`	List categories
`immybot_software_publishers`	List publishers
`immybot_software_install`	Stage software installation
`immybot_software_stats`	Get installation statistics

Error Handling

The server provides structured error responses:

{
  "content": [{"type": "text", "text": "Error: Authentication failed"}],
  "isError": true
}

Common error types:

Authentication errors - Invalid credentials or expired tokens
Not found errors - Resource doesn't exist
Validation errors - Missing or invalid parameters
Rate limit errors - Too many requests
Server errors - Internal ImmyBot API issues

Development

Build from Source

git clone https://github.com/WYRE-AI/immybot-mcp.git
cd immybot-mcp
npm install
npm run build
npm start

Testing

npm test

Docker Build

docker build -t immybot-mcp --secret id=npmrc,src=$HOME/.npmrc .

The checked-in Compose file is gateway mode. It requires CONDUIT_S2S_SECRET and does not pass static IMMYBOT_* credentials.

Support

License

Apache-2.0 - see LICENSE for details.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install ImmyBot?

Does ImmyBot need an API key?

What transport does ImmyBot use?

When was ImmyBot last checked?

Documentation

@wyre-ai/immybot-mcp

Features

Quick Start

Docker (Recommended)

Direct Installation

Navigation

Available Domains

Authentication

Required Configuration

Setup Steps

Usage Examples

1. Navigate to Computers Domain

2. Software Management

3. Maintenance Sessions

Two-Step Deployment Model

Environment Variables

Gateway Mode (Docker)

Direct Mode (CLI)

HTTP authentication

Tools Reference

Navigation Tools

Computers Tools

Software Tools

Error Handling

Development

Build from Source

Testing

Docker Build

Support

License