ITGlue MCP Server

A comprehensive Model Context Protocol (MCP) server for the ITGlue API. Provides 139 tools covering the full ITGlue API surface with built-in caching, token optimization, deduplication detection, and bulk operations.

Features

• 139 MCP tools spanning 29 ITGlue resource categories
• Token optimization — compact/standard/detailed response modes, field selection, empty-field omission (up to 80% token reduction)
• Smart caching — LRU cache with per-resource TTLs, pattern-based invalidation (50-90% fewer API calls)
• Deduplication detection — fuzzy string matching with confidence scoring for organizations, contacts, and configurations
• Bulk operations — batch GET (up to 50 resources per call), bulk PATCH/DELETE for all major resource types
• Full document lifecycle — create, section management, image upload, publish, and an embedded documentation standard
• Rate limiting — automatic throttling (3000 req/5min) with exponential backoff

Quick Start

1. Install

npm install @wilnertech/itglue-mcp-server

Or clone and build from source:

git clone https://github.com/WilnerTech/itglue-mcp-server.git
cd itglue-mcp-server
npm install
npm run build

2. Configure

Copy .env.example to .env and set your API key:

cp .env.example .env

ITGLUE_API_KEY=your-api-key-here

3. Add to your MCP client

Claude Code (.mcp.json):

{
  "mcpServers": {
    "itglue": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/itglue-mcp-server/dist/index.js"],
      "env": {
        "ITGLUE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

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

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | ITGLUE_API_KEY | Yes | — | ITGlue API key (Admin > Settings > API Keys) | | ITGLUE_BASE_URL | No | https://api.itglue.com | API base URL (change for EU: https://api.eu.itglue.com) | | ITGLUE_CREDENTIAL_ORG | No | — | Organization name for credential lookup (get_itglue_credential) | | ITGLUE_CREDENTIAL_FOLDER | No | — | Password folder name to scope credential search |

Tool Catalog

Core Resources (CRUD + Search)

| Category | Tools | Operations | |----------|-------|------------| | Organizations | 5 | list, get, search, create, update | | Contacts | 6 | list, get, search_by_email, create, update, delete | | Configurations | 6 | list, get, search_by_serial, create, update, delete | | Passwords | 6 | list, get, create, update, archive, credential_lookup | | Password Folders | 5 | list, get, create, update, delete | | Locations | 7 | list, get, search, find_match, create, update, delete |

Documents & Content

| Category | Tools | Operations | |----------|-------|------------| | Documents | 6 | list, get, create, update, publish, bulk_delete | | Document Sections | 5 | list, get, create, update, delete | | Document Images | 3 | get, create, delete | | Documentation Standard | 1 | get (embedded ITGlue doc-writing guide) |

Flexible Assets

| Category | Tools | Operations | |----------|-------|------------| | Flexible Assets | 7 | list_types, list, get, search_by_traits, create, update, delete | | Flexible Asset Fields | 5 | list, get, create, update, delete |

Deduplication

| Category | Tools | Operations | |----------|-------|------------| | Deduplication | 4 | find_org_match, find_contact_match, find_config_match, scan_duplicates |

Confidence thresholds: >=95% Update, 80-94% ManualReview, <80% CreateNew

Lookups & Reference Data

| Category | Tools | Operations | |----------|-------|------------| | Configuration Interfaces | 5 | list, get, create, update, delete | | Configuration Statuses | 4 | list, get, create, update | | Organization Types | 4 | list, get, create, update | | Organization Statuses | 4 | list, get, create, update | | Reference Data | 1 | list (manufacturers, models, OSes, platforms, regions, countries, domains) |

Users, Groups & Audit

| Category | Tools | Operations | |----------|-------|------------| | Users | 3 | list, get, update | | User Metrics | 1 | list | | Groups | 5 | list, get, create, update, delete | | Exports | 4 | list, get, create, delete | | Logs | 1 | list |

Relationships & Attachments

| Category | Tools | Operations | |----------|-------|------------| | Related Items | 3 | list, create, delete | | Attachments | 5 | list, get, create, update, delete | | Checklists | 4 | list, get, update, delete |

Bulk & Batch Operations

| Category | Tools | Operations | |----------|-------|------------| | Batch GET | 3 | organizations, configurations, contacts (up to 50 IDs per call) | | Bulk Write | 15 | bulk_update/delete for orgs, contacts, configs, passwords, locations, flexible_assets, password_folders |

Token Optimization

Every list/get tool supports format_options for token reduction:

{
  "format_options": {
    "format": "compact",
    "fields": ["id", "name", "status"],
    "omit_empty": true
  }
}

| Mode | Reduction | Description | |------|-----------|-------------| | compact | 30-50% | IDs + key fields only | | standard | 0% | Full response (default) | | detailed | 0% | Pretty-printed JSON | | Field selection | 40-70% | Return only specified fields | | omit_empty | 10-30% | Strip null/empty values | | Combined | up to 80% | All optimizations together |

Caching

Automatic in-memory LRU cache with per-resource TTLs:

| Data Type | TTL | Rationale | |-----------|-----|-----------| | Reference data (types, folders) | 1 hour | Rarely changes | | Organizations, locations | 5 minutes | Moderate change rate | | Configurations, contacts | 1 minute | Frequent updates | | Passwords | No cache | Security-sensitive |

Write operations automatically invalidate relevant cache entries.

Credential Lookup

The get_itglue_credential tool retrieves API credentials using a naming convention:

API - {Application} - {Qualifier}

Setup: Set ITGLUE_CREDENTIAL_ORG (and optionally ITGLUE_CREDENTIAL_FOLDER) in your environment.

Example: Looking up application: "HaloPSA", qualifier: "Production" searches for a password named API - HaloPSA - Production in the configured organization.

Rate Limiting

Built-in automatic rate limiting:

• Limit: 3000 requests per 5-minute window (ITGlue default)
• Min interval: 100ms between requests
• Retry: Exponential backoff on 429/5xx (3 attempts: 1s, 2s, 4s)

Error Handling

All errors return structured JSON with actionable suggestions:

| HTTP Status | Error Type | Auto-Retry | |-------------|-----------|------------| | 401 | Authentication | No | | 403 | Forbidden | No | | 404 | Not Found | No | | 422 | Validation | No | | 429 | Rate Limit | Yes | | 5xx | Server Error | Yes |

Project Structure

src/
├── api/
│   ├── client.ts              # API client with rate limiting & caching
│   ├── errors.ts              # Structured error handling
│   └── similarity.ts          # String similarity (Levenshtein)
├── cache/
│   └── memory-cache.ts        # LRU cache with TTL
├── schemas/
│   └── common.ts              # Shared Zod schemas
├── tools/                     # 29 tool files, one per resource category
│   ├── organizations.ts
│   ├── contacts.ts
│   ├── configurations.ts
│   ├── passwords.ts
│   ├── documents.ts
│   ├── document-sections.ts
│   ├── document-images.ts
│   ├── documentation-standard.ts
│   ├── deduplication.ts
│   ├── flexible-assets.ts
│   ├── bulk-write-operations.ts
│   └── ...
├── types/
│   └── itglue.ts              # TypeScript interfaces (30+)
├── utils/
│   ├── formatter.ts           # Token-optimized response formatting
│   └── bulk.ts                # Bulk operation helpers
└── index.ts                   # MCP server entry point

Development

npm run build       # Compile TypeScript
npm run dev         # Watch mode
npm run lint        # ESLint
npm run format      # Prettier
npm start           # Run server

Adding a Tool

1. Create or edit src/tools/{category}.ts
2. Export a Zod schema and async handler function
3. Register in src/index.ts (ListTools + CallTool handlers)
4. npm run build

Contributing

1. Fork the repository
2. Create a feature branch
3. Follow TypeScript strict mode
4. Add Zod validation for all inputs
5. Include error handling for API calls
6. Submit a pull request

License

MIT

Links

• ITGlue API Documentation
• Model Context Protocol
• MCP TypeScript SDK