mcp-itglue
This server gives AI assistants read and controlled write access to IT Glue documentation and assets via the Model Context Protocol.
Organizations – search and list organizations, or fetch one by ID
Documents – list, read, create (as draft), rename, publish, and permanently delete documents
Document folders – browse folders to place documents
Document sections – list, read, add Text/Heading/Gallery/Step sections, update content/position, and delete sections
Document images – upload images inline or into galleries from base64, URL, local path, or staged upload; get and delete images
Attachments – attach files to records, list attachments, and delete them
Flexible assets – list asset types and assets, inspect type fields, create/update/delete assets with trait values
Vector search – build and query a semantic search index over documents using OpenAI/Azure OpenAI embeddings
Index freshness – automatic refresh after writes, IT Glue webhook updates, and manual refresh endpoint
Access control – viewer/editor/admin role tokens and optional bring-your-own IT Glue API key per session
Advanced toolset – read-only passthrough GET and endpoint discovery (opt-in)
Provides semantic vector search capabilities using OpenAI embeddings, enabling natural language queries against IT Glue documentation and assets.
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
<img src>; get and delete document imagesAttachments — 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):
{
"mcpServers": {
"itglue": {
"command": "npx",
"args": ["-y", "mcp-itglue"],
"env": { "ITGLUE_API_KEY": "ITG.xxxx" }
}
}
}Claude Code one-liner:
claude mcp add itglue --env ITGLUE_API_KEY=ITG.xxxx -- npx -y mcp-itglueClaude 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):
docker run --rm -p 3000:3000 \
-e ITGLUE_API_KEY=ITG.xxxx \
ghcr.io/mspstack/mcp-itglueFor local stdio use under Docker:
{
"mcpServers": {
"itglue": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "ITGLUE_API_KEY", "ghcr.io/mspstack/mcp-itglue", "--transport", "stdio"],
"env": { "ITGLUE_API_KEY": "ITG.xxxx" }
}
}
}From source
git clone https://github.com/mspstack/mcp-itglue.git && cd mcp-itglue
npm install && npm run build
ITGLUE_API_KEY=ITG.xxxx node dist/index.jsRelated MCP server: IT Glue MCP Server
HTTP deployment
ITGLUE_API_KEY=ITG.xxxx \
MCP_TOKENS_VIEWER="alice:$(openssl rand -hex 32)" \
MCP_TOKENS_EDITOR="automation:$(openssl rand -hex 32)" \
MCP_TOKENS_ADMIN="ops:$(openssl rand -hex 32)" \
npx -y mcp-itglue --transport http --port 3000Or with Docker:
docker run --rm -p 3000:3000 \
-e ITGLUE_API_KEY -e MCP_TOKENS_VIEWER -e MCP_TOKENS_EDITOR -e MCP_TOKENS_ADMIN \
ghcr.io/mspstack/mcp-itglueEndpoints:
Route | Purpose |
| MCP streamable-http endpoint |
| Liveness probe |
| IT Glue webhook → incremental index update |
| Manual index refresh (shared secret or admin token) |
| Staged file upload slot (memory backend; same auth as |
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:
MCP_TOKENS_VIEWER="alice:tokA,bob:tokB" # read-only tools
MCP_TOKENS_EDITOR="hatz:tokC" # + create/update/publish, delete section
MCP_TOKENS_ADMIN="ops:tokD" # + delete documents / flexible assetsClients authenticate with Authorization: Bearer <token>. 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 |
| BYOK allowed, but a valid bearer token is still required — protects your server from being an open proxy |
| An IT Glue key alone authenticates (trusted networks / local use) |
| The header is rejected; only the server-wide key is used |
With BYOK enabled the server-wide ITGLUE_API_KEY becomes optional: sessions without a client key are rejected with a clear error. Client keys are never logged; sessions are bound to a SHA-256 hash of the key and audit-labeled byok:<hash-prefix>.
Tools
Tool | Tier |
| read |
| read |
| read |
| read |
| read |
| read |
| read |
| read |
| read |
| write |
| write |
| write |
| write |
| write |
| write |
| write |
| write |
| write |
| destructive |
| destructive |
| destructive |
| read |
Viewer = read. Editor = read + write. Admin = everything.
† Permanent, but editor-tier: editors need these to restructure documents and can already blank section content (or edit an <img> out of it) via update.
Images in documents vs. attachments
IT Glue has two unrelated upload paths. Attachments (itglue_create_attachment) land in a record's Attachments side panel and never render in a document's body. To show a picture inside a document, use itglue_create_document_image:
Upload with
document_id(inline) ordocument_id+gallery_id(thedocument_gallery_idof a Gallery/Step section).For inline images, put the returned
inline_resource_urlverbatim into the section HTML:<img src="/6255696/docs/17772862/images/27211966">— or passappend_to_section_idand the tool appends it to an existing Text/Step section for you.
IT Glue strips data: URIs and its own S3 URLs from section content; only these relative paths (and public https:// links) survive.
Getting a file from the client to the server (staged uploads)
Tool arguments travel through the model, so content_base64 only works for tiny files — a screenshot is megabytes of base64 the model would have to reproduce token by token (and IT Glue rejects the truncated result with NotIdentifiedByImageMagickError). Over HTTP the server therefore offers staged uploads:
The model calls
itglue_request_upload(file_nameoptional) and gets anupload_id, a URL, and a ready-to-runcurl.The client PUTs the file to that URL from a shell.
The model calls
itglue_create_document_imageoritglue_create_attachmentwithupload_id.
Slots live 15 minutes, are bound to the requesting principal (token label / BYOK key), and are consumed once. Two backends, chosen with UPLOAD_STAGING:
Mode | Where the PUT goes | When to use |
| This server's | The server is directly reachable by clients. |
| A short-lived SAS URL on Azure Blob Storage; the server later downloads the blob with its own credentials and deletes it. | The server sits behind a gateway or is otherwise not reachable from clients. Configure |
| — | stdio (default there — |
url remains the simplest source for anything already hosted on the web.
‡ Advanced toolset (opt-in, off by default): itglue_get is a read-only GET passthrough for any API path the curated tools don't wrap, and itglue_find_endpoint searches a curated endpoint catalog. Enable with ITGLUE_ADVANCED_TOOLSET=true or --advanced. Password resources (/passwords) are hard-blocked — credential values never reach the model.
Vector tools appear only when an embedding provider is configured.
Vector search
Set OPENAI_API_KEY (or AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT, where EMBEDDING_MODEL is your deployment name), then run itglue_build_vector_index per organization. The index is a JSON file at VECTOR_INDEX_PATH (default ./vector-index.json) — on ephemeral hosts, point it at a persistent volume.
The index stays fresh three ways:
IT Glue webhook — in IT Glue, webhooks are sent by Workflows (Admin → Workflows): add a Document trigger (created/updated) with a Webhook action. Workflow actions cannot send custom headers, so put the shared secret in the URL:
https://<host>/webhook/itglue?secret=<ITGLUE_WEBHOOK_SECRET>and use a JSON payload template like:
Key
Value
event[trigger_name]resource_url[resource_url]resource_name[resource_name]organization_name[organization_name]The document id is parsed from
resource_url; the trigger name maps to created/updated/deleted by keyword. Classic JSON:API-style payloads with anx-itglue-webhook-signatureHMAC-SHA256 header are also accepted.Self-refresh — documents created/updated/published/deleted through this server's tools are re-indexed automatically in the background.
Manual refresh —
POST /index/refreshwithAuthorization: Bearer <ITGLUE_WEBHOOK_SECRET>(or anx-refresh-secretheader, or an admin token). Body{"document_id": "123"}refreshes one document; an empty body re-crawls every indexed organization. Returns202and processes in the background.
Configuration reference
Variable | Default | Purpose |
| — | Server-wide IT Glue API key |
|
|
|
| per region | Override the API base URL |
|
|
|
|
| HTTP port |
| — |
|
|
| BYOK policy: |
| — | Extra browser origins allowed on |
|
|
|
| — | Webhook signature + |
|
| Vector index file |
| — | Enables vector search (OpenAI) |
| — | Enables vector search (Azure OpenAI) |
|
| Embedding model / Azure deployment |
CLI flags --transport, --port, --region, --base-url, --advanced override the environment. Run mcp-itglue --help for details.
Notes & limits
IT Glue rate limit: 3000 requests / 5 minutes per key.
The IT Glue documents API is only partially documented; document/section endpoints follow observed API behavior.
Flexible-asset trait updates replace the whole traits object — the update tool's description warns the model to send all traits back.
List tools return summary fields per item (in both text and
structuredContent) so default page sizes stay within client token limits; theitglue_get_*tools return the complete record.IT Glue has no user impersonation: a given API key always acts as itself. RBAC here controls what tool calls a session may make; BYOK delegates to IT Glue's own key permissions.
Development
npm install
npm run dev # stdio via tsx
npm run dev:http # http via tsx
npm test # vitest
npm run build # tsc → dist/Author
Built by Eugene Samotija (@selic) — defency.net. More projects: github.com/selic · LinkedIn
License
Available Tools
27 toolsitglue_create_attachmentCreate IT Glue AttachmentA
Attach a file (PDF, image, config export, …) to a record (document, flexible asset, configuration, etc.). The file appears in the record's Attachments side panel — it is NOT shown inside a document's body. To place a picture inside a document (inline in a Text/Step section or in a Gallery), use itglue_create_document_image instead. Provide exactly one source: content_base64 (small files only), url (the server fetches it), file_path (local stdio runs only), or upload_id (a file the client PUT via itglue_request_upload — use this for anything on the client's disk). Give file_name with an extension (e.g. network-diagram.pdf) so IT Glue detects the type; it is inferred from url/file_path/upload when omitted. Max 25 MB.
Inputs: resource_id (required), resource_type (required), url, file_name, +4 more.
itglue_create_documentCreate IT Glue DocumentA
Create a new document as a DRAFT in an organization. Add content with itglue_create_document_section, then make it visible with itglue_publish_document.
Inputs: name (required), organization_id (required), response_format, document_folder_id.
itglue_create_document_imageCreate IT Glue Document ImageA
Upload a picture INTO a document — the only way to get an image to render in a document's body (itglue_create_attachment only files it in the Attachments panel). Two placements: (1) INLINE — omit gallery_id; the result carries inline_resource_url, a relative path you must use verbatim as in Text/Step section HTML via itglue_create_document_section or itglue_update_document_section, or pass append_to_section_id to have this tool append the to an existing Text/Step section for you. (2) GALLERY — pass gallery_id (the document_gallery_id shown on a Gallery or Step section) to file the image into that gallery. Never put base64/data: URIs or S3 URLs in section content; IT Glue strips them. Provide exactly one source: upload_id (a file the client PUT via itglue_request_upload — the right choice for anything on the client's disk), url (the server fetches it), file_path (local stdio runs only), or content_base64 (tiny files only). content_base64 must be the exact bytes of a real image file — never write or reconstruct base64 yourself (IT Glue rejects anything ImageMagick cannot decode). file_name needs an extension (e.g. screenshot.png); inferred from url/file_path when omitted. Max 25 MB.
Inputs: document_id (required), url, file_name, file_path, +5 more.
itglue_create_document_sectionCreate IT Glue Document SectionA
Add a section to a document. Types: Text (HTML content), Heading (content = heading text, level 1-6 required), Gallery (no content — add pictures afterwards with itglue_create_document_image using the new section's document_gallery_id), Step (HTML content, optional duration in minutes). IMAGES: to show a picture in Text/Step HTML, first upload it with itglue_create_document_image and use the returned inline_resource_url verbatim as . Public https:// image links also work; base64/data: URIs and S3 URLs are stripped by IT Glue. Attachments never render in the body.
Inputs: document_id (required), section_type (required), sort, level, +3 more.
itglue_create_flexible_assetCreate IT Glue Flexible AssetA
Create a flexible asset. Traits are the type's fields keyed by their lowercased, hyphenated names (inspect them with itglue_get_flexible_asset_type). All required traits must be provided.
Inputs: traits (required), organization_id (required), flexible_asset_type_id (required), response_format.
itglue_delete_attachmentDelete IT Glue AttachmentADestructiveIdempotent
PERMANENTLY delete an attachment from a record. This cannot be undone. Find the attachment ID with itglue_list_attachments.
Inputs: resource_id (required), attachment_id (required), resource_type (required).
itglue_delete_document_imageDelete IT Glue Document ImageADestructiveIdempotent
PERMANENTLY delete a document image (all size variants). This cannot be undone. Any tag still referencing it stays in the section HTML until that section is next saved, when IT Glue drops the broken reference — remove the tag yourself with itglue_update_document_section for an immediate clean result.
Inputs: image_id (required), document_id.
itglue_delete_documentsDelete IT Glue DocumentsADestructiveIdempotent
PERMANENTLY delete one or more documents, including all their sections. This cannot be undone.
Inputs: document_ids (required).
itglue_delete_document_sectionDelete IT Glue Document SectionADestructiveIdempotent
PERMANENTLY delete one section from a document. This cannot be undone. Useful for restructuring a document's layout.
Inputs: section_id (required), document_id (required).
itglue_delete_flexible_assetDelete IT Glue Flexible AssetADestructiveIdempotent
PERMANENTLY delete a flexible asset. This cannot be undone.
Inputs: flexible_asset_id (required).
itglue_get_documentGet IT Glue DocumentARead-onlyIdempotent
Get a document by ID with all of its sections and their content. Section content is stored as HTML; markdown output converts it to plain text, with inline images shown as their relative /org/docs/doc/images/ID paths and gallery images listed by ID. If the response is truncated, fetch individual sections with itglue_get_document_section.
Inputs: document_id (required), response_format. Returns: item
itglue_get_document_imageGet IT Glue Document ImageARead-onlyIdempotent
Get one document image by ID: file name, size, owning document/gallery, the inline_resource_url to embed it with, and a presigned download URL (valid ~1 hour). Image IDs appear in section HTML as the last path segment of and in Gallery/Step section image lists.
Inputs: image_id (required), response_format. Returns: item
itglue_get_document_sectionGet IT Glue Document SectionARead-onlyIdempotent
Get one document section with its full content (HTML on the wire; markdown output converts to plain text). Inline images appear as relative paths — keep them verbatim when editing; the JSON record also has rendered_content with temporary S3 URLs for display.
Inputs: section_id (required), document_id (required), response_format. Returns: item
itglue_get_flexible_assetGet IT Glue Flexible AssetARead-onlyIdempotent
Get one flexible asset by ID, including all of its traits.
Inputs: flexible_asset_id (required), response_format. Returns: item
itglue_get_flexible_asset_typeGet IT Glue Flexible Asset TypeARead-onlyIdempotent
Get a flexible asset type by ID, including its field definitions (name, kind, required) — the trait keys needed to create or update assets of this type.
Inputs: flexible_asset_type_id (required), response_format. Returns: item
itglue_get_organizationGet IT Glue OrganizationBRead-onlyIdempotent
Get a single IT Glue organization by ID.
Inputs: organization_id (required), response_format. Returns: item
itglue_list_attachmentsList IT Glue AttachmentsARead-onlyIdempotent
List the attachments on a record (document, flexible asset, configuration, etc.), with attachment IDs (needed for delete), file names, content types, and download URLs.
Inputs: resource_id (required), resource_type (required), page_size, page_number, +1 more. Returns: items, has_more, page_number, total_count
itglue_list_document_foldersList IT Glue Document FoldersARead-onlyIdempotent
List the document folders (directories) in an organization, including nested folders. Returns summary metadata only (name, parent folder, document count). Use this to discover a document_folder_id for itglue_create_document, or to browse an organization's document tree. filter_name matches partially and case-insensitively; parent_id is the number in a folder's URL. A folder with parent_id null is top-level.
Inputs: organization_id (required), sort, filter_id, page_size, +3 more. Returns: items, has_more, page_number, total_count
itglue_list_documentsList IT Glue DocumentsARead-onlyIdempotent
List documents in an organization, including documents nested in folders. Returns summary metadata only — use itglue_get_document for content and the full record. filter_name matches partially and case-insensitively. The endpoint returns root-level documents by default, so this tool issues a second query for folder-nested documents and merges the results (up to 2x page_size items).
Inputs: organization_id (required), sort, filter_id, page_size, +3 more. Returns: items, has_more, page_number, total_count
itglue_list_document_sectionsList IT Glue Document SectionsARead-onlyIdempotent
List the sections of a document in position order, with content previews and section IDs (needed for update/delete operations). List items carry summary fields and a bounded content_preview; Gallery/Step items also carry document_gallery_id (the gallery_id for itglue_create_document_image) and their images. Use itglue_get_document_section for full content.
Inputs: document_id (required), page_size, page_number, response_format. Returns: items, has_more, page_number, total_count
itglue_list_flexible_assetsList IT Glue Flexible AssetsARead-onlyIdempotent
List flexible assets of a given type, optionally restricted to one organization. The type ID is required by the IT Glue API — find it with itglue_list_flexible_asset_types. List items show bounded trait previews (HTML stripped, long values truncated); use itglue_get_flexible_asset for full trait values.
Inputs: flexible_asset_type_id (required), page_size, page_number, organization_id, +1 more. Returns: items, has_more, page_number, total_count
itglue_list_flexible_asset_typesList IT Glue Flexible Asset TypesARead-onlyIdempotent
List flexible asset types (the schemas MSPs define in IT Glue, e.g. 'Wireless', 'Applications'). Use this to find the type ID required by itglue_list_flexible_assets. filter_name matches partially and case-insensitively. List items carry summary fields; use itglue_get_flexible_asset_type for field definitions.
Inputs: page_size, filter_name, page_number, response_format. Returns: items, has_more, page_number, total_count
itglue_list_organizationsList IT Glue OrganizationsARead-onlyIdempotent
Search and list IT Glue organizations. Use this first to find the organization ID required by document and flexible-asset tools. filter_name matches partially and case-insensitively; filter_id is exact. Results are paginated. List items carry summary fields; use itglue_get_organization for the full record.
Inputs: sort, filter_id, page_size, filter_name, +2 more. Returns: items, has_more, page_number, total_count
itglue_publish_documentPublish IT Glue DocumentAIdempotent
Publish a draft document, making it visible to users with access.
Inputs: document_id (required).
itglue_update_documentUpdate IT Glue DocumentAIdempotent
Rename a document (metadata only). To change content, use itglue_update_document_section.
Inputs: name (required), document_id (required), response_format.
itglue_update_document_sectionUpdate IT Glue Document SectionAIdempotent
Update a section's content, heading level, duration, or position. Only provided fields change; the section type cannot be changed. content REPLACES the whole HTML — fetch the current content first and keep existing tags verbatim, or they are lost. To add a new picture, upload it with itglue_create_document_image (or its append_to_section_id shortcut) and embed the returned inline_resource_url; base64/data: URIs and S3 URLs are stripped by IT Glue.
Inputs: section_id (required), document_id (required), sort, level, +3 more.
itglue_update_flexible_assetUpdate IT Glue Flexible AssetAIdempotent
Update a flexible asset's traits. IMPORTANT: IT Glue replaces the traits object wholesale — fetch the asset first and send back ALL traits, not just the changed ones, or omitted traits are cleared.
Inputs: traits (required), flexible_asset_id (required), response_format.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 27 tools
Each tool targets a distinct resource and action, with clear separation between documents, sections, images, attachments, flexible assets, and organizations. Descriptions explicitly contrast similar tools (e.g., itglue_create_attachment vs itglue_create_document_image) to prevent confusion.
All tools follow the consistent itglue_verb_noun pattern using snake_case. Verbs are uniformly get, create, update, delete, list, and publish, and nouns precisely identify the resource (document, document_section, flexible_asset, etc.).
27 tools is above the typical range, but the server covers a broad domain with multiple entities (documents, sections, images, attachments, flexible asset types and assets, organizations). Each tool serves a specific purpose, and the count is justified by the API's complexity, though it is on the heavy side.
The core CRUD lifecycle is well covered for documents, sections, images, attachments, and flexible assets, but there are gaps: document folders only support listing (no create/update/delete), and the referenced itglue_request_upload tool is not exposed in the tool set, creating a missing dependency for upload workflows.
Maintenance
Related MCP Connectors
Connect ChatGPT or Claude to your CRM, store or shipping API. Keys stay out of the chat.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
Enhanciar is an AI company brain for every team. It reads your Slack, Gmail, Google Drive, Notion, Confluence, Jira, Linear, Zendesk, GitHub code and databases, writes a wiki from them, and answers questions from any MCP client with a link to the source. Tools: query (cited answers), search_wiki, get_page, list_pages, get_graph, get_process_map, impact (what a code change touches), list_repos, list_skills, get_skill, propose_action and list_proposed_actions (tickets, Slack messages, Gmail drafts, Notion pages and calendar holds that a person approves first). Hosted service, bring your own AI key. Plans: Solo $24 a month, Team $100 a month for up to 10 people. Create an API key in Settings at https://enhanciar.in.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn unofficial Model Context Protocol server that enables AI assistants to manage ITGlue documents, sections, and organizations via the ITGlue API. It supports full CRUD operations, organization lookups, and regional API endpoints for US, EU, and Australia.44 npm5MIT
- AlicenseAqualityCmaintenanceProvides Claude with access to IT Glue documentation and asset management, enabling search, retrieval, and creation of organizations, configurations, locations, passwords, documents, attachments, flexible assets, and user activity metrics through the IT Glue API.28Apache 2.0
- AlicenseBqualityCmaintenanceEnables AI assistants to interact with IT Glue's documentation and asset management system, including CRUD operations on organizations, configurations, passwords, flexible assets, documents, and related reference data.105MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to read and update IT Glue documentation, including organizations, configurations, locations, passwords, documents, attachments, flexible assets and user activity metrics, through a stateless HTTP service behind the MSPbots MCP gateway.Apache 2.0