
ImmyBot
io.github.WYRE-AIPublished by GitHub account WYRE-AIv2.0.0Updated Nov 21, 2026
MCP server for ImmyBot — Windows software deployment, maintenance, tenants, deployments.
Overview
Connects an assistant to ImmyBot for Windows endpoint management: listing computers, staging software installs, running maintenance sessions and checking tasks.
- What you can do
- List, search, inspect and create computers, view inventory and deployments, and force agent check-in
- Browse, search and inspect software packages, versions, categories and publishers, and stage installations
- Start and check maintenance sessions that reconcile desired state onto devices
- Manage tenants, PowerShell scripts and background tasks
- Report server status and tool groups
- When to use it
- Useful for MSP or IT admins who manage Windows fleets in ImmyBot and want an assistant to look up devices, plan software rollouts, or trigger and follow maintenance sessions without switching to the web console.
- Requirements
- Runs as a local process (npm package or container image) over stdio, or as an HTTP service for gateway hosting. Direct mode needs IMMYBOT_INSTANCE_SUBDOMAIN, IMMYBOT_TENANT_ID, IMMYBOT_CLIENT_ID and IMMYBOT_CLIENT_SECRET from a Microsoft Entra ID app registration with ImmyBot API permissions. HTTP mode also needs CONDUIT_S2S_SECRET and X-Gateway-S2S signing; gateway mode expects the four X-ImmyBot-* headers per request.
Installation
In SourceWeft
- Open ImmyBot in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
@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
- 🧭 Flat Tool List - Every tool is listed and callable immediately
- 💻 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.
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:
Direct Installation
Tools
Every tool is listed by tools/list and callable immediately. There is no
domain to enter first. The domains below are documentation groupings only.
Upgrading from 1.x?
immybot_navigateandimmybot_backare gone. Call the domain tools directly, for exampleimmybot_computers_list.immybot_statusstill works and now lists the tool groups.
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
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. Computers
2. Software Management
3. Maintenance Sessions
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
Environment Variables
Copy .env.example and set the variables below.
Gateway Mode (Docker)
/health stays unauthenticated and does not read credentials. The stdio transport does not use CONDUIT_S2S_SECRET.
Direct Mode (CLI)
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.
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.
Tools Reference
Status Tool
Computers Tools
Software Tools
Error Handling
The server provides structured error responses:
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
Testing
Docker Build
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.
Source: README.md at commit dc8d0f0
Tools
0Version history
3- v2.0.0LatestNov 20, 2026
- v1.2.14Oct 14, 2026
- v1.2.13Sep 16, 2026
Score
40% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts
Declare a license in the repository or the registry entry.