itglue-mcp

A Model Context Protocol (MCP) server for the ITGlue API, by WIT-SecOps. It lets AI assistants read and manage ITGlue documents and sections, read organizations, configurations, contacts, locations, domains, expirations, and flexible assets, and search everything through a local content-search index.

Note: Not affiliated with or endorsed by Kaseya/ITGlue.

Features

• 48 tools covering documents, document sections, organizations, configurations (with network interfaces, type/status lookups, and manufacturer/model lookups), contacts, locations, domains, expirations, flexible assets, and a local search index
• Full CRUD support for documents, document sections, configurations, and contacts; full CRUD for flexible assets; create/update for configuration interfaces
• Read-only access to organizations, configuration interfaces (network IP/MAC detail), configuration types and statuses, contacts, locations, domains, expirations, and flexible assets (plus flexible asset types)
• Publish documents directly from your AI assistant
• Organization lookup for finding org IDs
• Pagination, filtering, and sorting support
• Local, entity-aware search index for fast keyword search across documents, configurations, contacts, locations, domains, and flexible assets — titles for all organizations plus per-organization body content, stored compressed on disk
• Markdown and JSON response formats
• Regional API support (US, EU, Australia)
• Runs locally over stdio — each MCP client spawns its own process

Quick Start

Claude Desktop

1. Open Claude Desktop and go to Settings > Developer > Edit Config
2. Add the following to claude_desktop_config.json:

{
  "mcpServers": {
    "itglue": {
      "command": "npx",
      "args": ["-y", "@wit-secops/itglue-mcp@latest"],
      "env": {
        "ITGLUE_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Save the file and restart Claude Desktop

This starts the server read-only (the default). To let authorized users' assistants modify ITGlue, use the read/write configuration in Access Modes.

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Other MCP Clients (Cursor, Windsurf, Claude Code, etc.)

Most MCP clients use the same stdio configuration format shown above.

EU or Australia Regions

Add --region eu or --region au to the args:

{
  "mcpServers": {
    "itglue": {
      "command": "npx",
      "args": ["-y", "@wit-secops/itglue-mcp@latest", "--region", "eu"],
      "env": {
        "ITGLUE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Environment Variables

| Variable | Description | Required | Default | |----------|-------------|----------|---------| | ITGLUE_API_KEY | ITGlue API key | Yes | | | ITGLUE_BASE_URL | Custom API base URL | No | https://api.itglue.com | | ITGLUE_ALLOW_WRITE | Enable the write tools (true to allow) | No | read-only |

CLI Options

--api-key <key>         ITGlue API key (overrides env var)
--base-url <url>        Custom API base URL (overrides env var)
--region <region>       API region: us, eu, or au (default: us)
--read-write            Enable write tools (default: read-only)
--read-only             Force read-only mode (the default)
--help                  Show help
--version               Show version

Access Modes (read-only vs read/write)

The server is read-only by default: it exposes the read/search tools — every list/get resource plus the local search index — but not the nineteen write tools (seven for documents/sections; three each for configurations and contacts; create/update/update (bulk)/delete for flexible assets; and create/update for configuration interfaces). Pass --read-write (or set ITGLUE_ALLOW_WRITE=true) to enable those.

Because writes are opt-in per launch, you hand out one of two configurations depending on whether a person's assistant should be able to modify ITGlue. The only difference between them is the --read-write argument.

Read-only (the default) — give this to everyone who only needs to look things up:

{
  "mcpServers": {
    "itglue": {
      "command": "npx",
      "args": ["-y", "@wit-secops/itglue-mcp@latest"],
      "env": {
        "ITGLUE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Read/write — give this only to authorized users:

{
  "mcpServers": {
    "itglue": {
      "command": "npx",
      "args": ["-y", "@wit-secops/itglue-mcp@latest", "--read-write"],
      "env": {
        "ITGLUE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Each person uses one block or the other. If you ever register both on the same machine, give them distinct keys (e.g. itglue and itglue-write) so they don't collide. For EU/AU, add "--region", "eu" (or "au") to args.

Access control: the mode flag separates intent and prevents accidental writes, but it is not by itself a security boundary — whoever launches the server supplies the API key and chooses the mode. To actually restrict who can write, hand the --read-write configuration (and, where possible, a separate write-capable API key) only to authorized people; everyone else runs the default read-only server.

Tools

Organizations

| Tool | Description | |------|-------------| | itglue_list_organizations | Search and list organizations with filtering and pagination; filter_short_name resolves a short code (e.g. WIT) to one org | | itglue_get_organization | Get detailed information about a specific organization |

Configurations

| Tool | Description | |------|-------------| | itglue_list_configurations | List/search an organization's configurations (servers, firewalls, switches, workstations) with filtering and pagination | | itglue_get_configuration | Get full details for a specific configuration (IPs, serial, notes, etc.) | | itglue_create_configuration | Create a configuration (requires type and status IDs; optional location, manufacturer, model, position) — write | | itglue_update_configuration | Update a configuration's fields, including location, manufacturer, model, and position — write | | itglue_delete_configurations | Permanently delete one or more configurations by ID — write | | itglue_list_configuration_interfaces | List a configuration's network interfaces (IP address, MAC address, primary flag) | | itglue_get_configuration_interface | Get full details for a specific configuration interface | | itglue_create_configuration_interface | Add an interface to a configuration — an iDRAC/iLO/IPMI management address or a second NIC — write | | itglue_update_configuration_interface | Update an interface (interfaces cannot be deleted via the API) — write | | itglue_list_configuration_types | List account-wide configuration types; use it to resolve the ID for filter_configuration_type_id | | itglue_list_configuration_statuses | List account-wide configuration statuses; use it to resolve the ID for filter_configuration_status_id | | itglue_list_manufacturers | List account-wide hardware manufacturers; resolves manufacturer_id for the configuration write tools | | itglue_list_models | List account-wide hardware models (narrow with filter_manufacturer_id); resolves model_id |

Contacts

| Tool | Description | |------|-------------| | itglue_list_contacts | List/search an organization's contacts (people) with filtering and pagination | | itglue_get_contact | Get full details for a contact (all emails, phone numbers, title, location, notes) | | itglue_create_contact | Create a contact (requires organization + first name; optional primary email) — write | | itglue_update_contact | Update a contact's scalar fields (not emails/phones) — write | | itglue_delete_contacts | Permanently delete one or more contacts by ID — write |

Locations

| Tool | Description | |------|-------------| | itglue_list_locations | List/search an organization's locations (sites/addresses) with filtering and pagination | | itglue_get_location | Get full details for a location (address, phone, fax, notes) |

Domains

| Tool | Description | |------|-------------| | itglue_list_domains | List/search an organization's domains, including registrar and expiry date (list-only — the API has no single-domain show endpoint) |

Expirations

| Tool | Description | |------|-------------| | itglue_list_expirations | List an organization's upcoming/past expirations (domains, SSL certificates, warranties, etc.) with a days-to-expiry range filter | | itglue_get_expiration | Get full details for a specific expiration (linked resource, type, and date) |

Flexible Assets

| Tool | Description | |------|-------------| | itglue_list_flexible_asset_fields | List a type's field definitions — each field's traits key, kind, required flag, and expected value; call before creating an asset | | itglue_list_flexible_asset_types | List the account's flexible asset types (templates); use it to discover the type ID required to list assets | | itglue_get_flexible_asset_type | Get details for a specific flexible asset type | | itglue_list_flexible_assets | List/search flexible assets of a single type (optionally scoped to one organization) | | itglue_get_flexible_asset | Get a flexible asset with all of its trait (field) values | | itglue_create_flexible_asset | Create a flexible asset from a traits object keyed by trait key — write | | itglue_update_flexible_asset | Update an asset's traits (reads and merges first, since ITGlue's PATCH replaces them) — write | | itglue_update_flexible_assets | Apply that same merge to up to 50 assets in one call, each with its own traits — write | | itglue_delete_flexible_assets | Permanently delete one or more flexible assets by ID — write |

Documents

| Tool | Description | |------|-------------| | itglue_list_documents | List documents globally or within an organization | | itglue_get_document | Get a document with all embedded sections | | itglue_create_document | Create a new draft document | | itglue_update_document | Update document metadata (name) | | itglue_publish_document | Publish a draft document | | itglue_delete_documents | Permanently delete one or more documents |

Document Sections

| Tool | Description | |------|-------------| | itglue_list_document_sections | List all sections in a document | | itglue_get_document_section | Get a specific section with full content | | itglue_create_document_section | Add a section (Text, Heading, Gallery, Step) | | itglue_update_document_section | Update section content, type, or position | | itglue_delete_document_section | Permanently delete a section |

Search Index

| Tool | Description | |------|-------------| | itglue_index_documents | Build/update the local search index (titles for all orgs; content per org) | | itglue_search_documents | Fast keyword search over the index (no live API calls) | | itglue_index_status | Report what is cached, sizes, and staleness (summary by default; detail: "full" lists every organization) |

Search & Filtering

filter_name on the list tools (itglue_list_documents, itglue_list_organizations, itglue_list_configurations, itglue_list_configuration_interfaces, itglue_list_configuration_types, itglue_list_configuration_statuses, itglue_list_contacts, itglue_list_locations, itglue_list_domains, itglue_list_flexible_asset_types, and itglue_list_flexible_assets) performs a case-insensitive substring match. The ITGlue API cannot filter documents by name (and its other name filters are exact-match only), so name filtering is applied client-side: the tool retrieves the full list for the scope and matches locally, then paginates. ID, type, and status filters are exact and applied server-side. When you already know the exact ID, prefer filter_id to avoid fetching the whole list.

filter_manufacturer_id on itglue_list_models is matched client-side for the same reason: ITGlue ignores filter[manufacturer-id] on /models and returns every model.

filter_short_name on itglue_list_organizations matches an organization's short name (its 3-letter code, e.g. WIT) exactly and case-insensitively. It is matched client-side too: the ITGlue API silently ignores a short-name filter and returns the full list, so forwarding it would appear to work while returning everything. Exact rather than substring matching is deliberate — codes must not collide (CAP should not also match CAPS). Use this rather than passing a code to filter_name, which matches the full organization name only.

Local Search Index

The ITGlue API has no full-text search and cannot filter by name, which makes "find the thing about X" hard across a large instance. This server adds a local, on-disk index you build explicitly and then search instantly (search never calls the API). The index is entity-aware: it covers documents, configurations, contacts, locations, domains, and flexible assets (pass entity_type when building).

Two tiers:

• Titles — cheap, covers all organizations. Build with itglue_index_documents (no organization_id). Pass entity_type (e.g. "configurations", "contacts") to index that entity's titles instead of documents. Note: an all-organizations flexible_assets title sweep is comparatively expensive (the API requires listing per asset type), so prefer scoping it to one organization.
• Content — opt-in and per organization. For documents this costs roughly one API call per document; for configurations, contacts, locations, domains, and flexible assets the searchable content (notes plus identifiers such as IPs, serials, emails, phone numbers, domain names, and flexible-asset traits) comes from the list record itself, so it needs no per-record fetch — making it much cheaper than documents. Build with itglue_index_documents using organization_id + include_content: true (+ entity_type as needed).

Build vs. update:

• mode: "full" rebuilds the scope from scratch.
• mode: "incremental" (default) re-sweeps titles cheaply, then re-fetches content only for added/changed records and drops deleted ones — so routine refreshes are fast.

Searching: itglue_search_documents ranks by keyword overlap (title matches weighted above content matches) and searches all indexed entity types by default — pass entity_types: ["configurations"] to restrict. Pass search_content: true to also match indexed body text. Use itglue_index_status to see per-entity coverage and staleness.

Storage & privacy: the cache is gzipped JSON. Content is stored only as a sorted, deduplicated set of keyword terms — word order and repetition are discarded, so the cache is compact and the original text cannot be reconstructed from it (identifiers like IPs and serials do survive as terms, which is what makes them searchable). Typical footprint: a few MB for ~100k titles; roughly a few hundred KB per 1,000-record content shard.

Cache location: defaults to a per-OS cache directory (%LOCALAPPDATA%\itglue-mcp\cache on Windows, ~/Library/Caches/itglue-mcp on macOS, $XDG_CACHE_HOME/itglue-mcp on Linux). Override with --cache-dir <path> or the ITGLUE_CACHE_DIR environment variable. The cache is namespaced by API host, so US/EU/AU instances don't collide.

API Key Setup

1. Log in to ITGlue as an Administrator
2. Go to Account > Settings > API Keys
3. Generate a new Custom API Key
4. Copy the key and set it as ITGLUE_API_KEY

ITGlue automatically revokes API keys unused for 90+ days.

Regions

| Region | Base URL | |--------|----------| | US (default) | https://api.itglue.com | | EU | https://api.eu.itglue.com | | Australia | https://api.au.itglue.com |

Rate Limiting

The ITGlue API allows a maximum of 3,000 requests per 5-minute window. The server will return clear error messages if the rate limit is exceeded.

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
ITGLUE_API_KEY=your-key node dist/index.js

# Development with auto-reload
ITGLUE_API_KEY=your-key npm run dev

# Run tests
npm test

# Everything the release runs: lint, format check, build, tests
npm run check

Pull requests don't run CI. A pre-push hook runs npm run check before anything leaves your machine instead. Turn it on once per clone:

git config core.hooksPath .githooks

Releasing

1. Bump version in package.json in the same PR as the change.
2. After merging to main, create a GitHub Release with a matching vX.Y.Z tag.
3. The release runs .github/workflows/publish.yml, which runs npm run check and then publishes to npm through Trusted Publishing (no stored token).

npm processes new versions asynchronously, so a release can take a few minutes to appear. Check with npm view @wit-secops/itglue-mcp version --prefer-online.

License

MIT