selic/mcp-itglue

An MCP (Model Context Protocol) server for the IT Glue API, built for MSPs that want AI assistants to read — and safely write — their documentation.
- **Documents & sections** — list, read, create, update, publish, delete
- **Flexible assets** — browse asset types and their fields, list/read/create/update/delete assets
- **Images inside documents** — upload a picture into a document (inline in a Text/Step section, or into a Gallery) from base64, a URL, or a local path, and embed it with the returned ; get and delete document images
- **Attachments** — attach any file to a record's Attachments panel (documents, flexible assets, configurations, …); list and delete attachments
- **Semantic vector search** — "how do I remove a backup agent" finds the Veeam decommissioning runbook, even when the words don't match (OpenAI or Azure OpenAI embeddings, local JSON index)
- **Role-based access control** — viewer / editor / admin bearer tokens decide which tools each session can even see
- **Bring your own key** — clients may supply their own IT Glue API key per session, so IT Glue's own permissions apply
- **Index freshness** — IT Glue webhook, post-write self-refresh, and a manual refresh endpoint
- **Transports** — stdio for local use, streamable HTTP for shared deployments; Docker image included
Installation
You need an IT Glue API key (IT Glue → Account → Settings → API Keys). Non-US accounts set ITGLUE_REGION to eu or au.
npx (recommended)
Claude Desktop (claude_desktop_config.json) or Claude Code (.mcp.json):
Claude Code one-liner:
Claude Desktop users can instead grab mcp-itglue.mcpb from the latest release — open it with Claude Desktop and fill in the API key when prompted.
stdio always runs with the full tool surface — it is a local, single-user transport using your own key.
Docker
The container image defaults to the HTTP transport (for shared deployments):
For local stdio use under Docker:
From source
HTTP deployment
Or with Docker:
Endpoints:
| Route | Purpose |
|---|---|
| POST/GET/DELETE /mcp | MCP streamable-http endpoint |
| GET /health | Liveness probe |
| POST /webhook/itglue | IT Glue webhook → incremental index update |
| POST /index/refresh | Manual index refresh (shared secret or admin token) |
| PUT /upload/:id | Staged file upload slot (memory backend; same auth as /mcp) |
> Sessions are held in memory — run a single instance (or add sticky sessions) behind your load balancer.
Access control
Role tokens
Three env vars hold comma-separated label:token lists:
Clients authenticate with Authorization: Bearer . The label appears in the audit log ([rbac] session … for alice (viewer)) and lets you revoke one person's token without rotating everyone's.
Tools a role cannot use are **not registered** for that session — a viewer doesn't even see itglue_create_document in tools/list — and a runtime guard re-checks the role on every call as defense in depth. Session ids never carry privilege: every request re-authenticates, and presenting a different principal against an existing session returns 403.
If **no** tokens are configured, the server runs in dev mode: all requests get admin access and a loud startup warning. Don't do this in production.
Bring your own IT Glue key (BYOK)
Clients may send their own IT Glue API key in the x-itglue-api-key header on the initialize request. The session then talks to IT Glue with **that** key and gets the full tool surface — IT Glue's own key permissions are the effective access control. CLIENT_ITGLUE_KEYS controls the policy:
| Value | Behavior |
|---|---|
| with-token (default) | BYOK allowed, but a valid bearer token is still required — protects your server from being an open proxy |
| open | An IT Glue key alone authenticates (trusted networks / local use) |
| disabled | The header is rejected; only the server-wide key is used |