NexTool MCP for GLPI

NexTool MCP for GLPI

Connect Claude and other MCP clients to your GLPI. One MCP server for both GLPI APIs; each tool family turns on with its own credentials:

Until 2.x the v2 family was a separate package (mcp-glpi-v2); since 3.0.0 it lives here, with the same tool names and schemas. Both families share the write policy, payload formatting and create idempotency below.

Not affiliated with Teclib'. GLPI is a registered trademark of Teclib'.

Tool selection. GLPI_TOOLSETS picks named presets (tickets,kb; see Toolsets); GLPI_TOOLS_INCLUDE / GLPI_TOOLS_EXCLUDE take comma-separated globs on tool names (glpi_*ticket*,glpi_search, *webhook*). Toolsets and include globs add up; exclude always wins; with neither toolsets nor include globs every tool registers. An unknown toolset name fails at startup. Fewer tools, less context per session.

Several instances can share this one binary with different env files.

Two ways to run

The HTTP entry is the one meant to serve every NexTool environment from one place. A key opens only the instances it was granted, a session stays bound to the key and instance that opened it, GLPI sessions, OAuth tokens and catalogue caches are kept per credential, and create idempotency is shared per instance across sessions. One JSON audit line per request goes to stdout (key, instance, methods, tools; never arguments or credentials). GET /healthz answers without authentication.

Keys live in the instances file as SHA-256 hashes only (mode 600; it is re-read when it changes):

{  "instances": {    "acme": { "env": { "GLPI_URL": "https://glpi.acme.example", "GLPI_USER_TOKEN": "…", "GLPI_APP_TOKEN": "…" } }  },  "keys": [{ "name": "laptop", "sha256": "<sha256 hex of the key>", "instances": ["acme"] }]}

KEY=$(openssl rand -hex 32)                       # give it to the client onceprintf %s "$KEY" | sha256sum | cut -d' ' -f1      # goes into "sha256"MCP_INSTANCES_FILE=instances.json MCP_HTTP_PORT=8787 npx mcp-glpi-http

A hosted, multi-tenant version with sign-in through the NexTool portal is available at https://mcp.nextoolsolutions.com/mcp.

Other variables: MCP_HTTP_HOST (default 127.0.0.1), MCP_ALLOWED_HOSTS (Host header allowlist), MCP_SESSION_IDLE_MIN (default 30). The file is re-read when it changes.

What it exposes

• 111 API v1 tools (60 read / 42 write / 9 destructive) over tickets, changes, problems, the unified timeline, validations, assets and reservations, webhooks, users, groups, entities, documents, the knowledge base, rules and search.

• 4 resources (glpi://entities, glpi://itil-categories, glpi://request-types, glpi://code-maps) so catalogue lookups do not cost a tool call.

• 4 prompts for triage, recurrence investigation, requester history and asset context. A prompt is offered only when every tool it names is registered (with GLPI_TOOLSETS=kb there is none).

• 55 API v2 tools (glpi_v2_*): entities, ITIL with team members and timeline, users, groups, knowledge base, dropdowns, documents, rules, session and health check.

Listing tickets

• glpi_list_my_tickets: role (any | requester | assigned | observer), status, sort, order, range, users_id (another user; default the session user from getFullSession). Rows carry requesters / assigned / observers as {id, name}, requester_groups, assigned_groups, status_name, type_name and my_roles; the result also has total and user.
• glpi_list_tickets: new status, sort and order (the old range and expand_dropdowns keep working). With a status filter the result also has total. Rows carry status_name, type_name, priority_name, category_name, and requesters / assigned as {id, name} (one search per 50 tickets, not one call per ticket).
• status takes one name or a list: new, assigned (= processing), planned, pending, solved, closed, and open (= new + assigned + planned + pending, GLPI's "not old").
• sort: date_mod (default), date, id, priority, status, name, solvedate, closedate; order: desc (default) or asc.
• glpi_v2_list_tickets takes the same status names and sorts by date_mod:desc by default. The v2 API cannot filter on the team (GLPI 11.0.7 ignores or rejects a team filter), so "my tickets" is a v1 tool.
• glpi_list_changes / glpi_list_problems (and the v2 ones) also default to latest update first.

Names next to IDs

Sub-items keep their IDs and gain names: glpi_list_ticket_users (user_name, type_name), glpi_list_ticket_groups (group_name, type_name), followups (user_name), tasks (user_name, tech_name, tech_group_name), validations (user_name, validator_name, status_name), glpi_list_timeline (all of these, plus solutiontype_name and user_name_approval on solutions), glpi_get_ticket (recipient_name, category_name, entity_name, requesttype_name, location_name, status_name, type_name, priority_name, urgency_name, impact_name), problems and changes (category_name, status_name, priority_name; the single item also the people and entity) and glpi_list_assets (location_name, state_name, user_name). Names are read with GET // through a 5-minute cache per credential; a name the user cannot read stays null.

Labels of codes (*_status, type_name, priority_name...) are in the language of the GLPI session (getFullSession → glpilanguage, cached per credential), with GLPI's own texts: pt_BR, pt_PT, es_ES, fr_FR, it_IT and de_DE have tables (taken from GLPI 11's locales/*.po), a regional variant uses its family (es_MX → es_ES), anything else GLPI's English. Before 3.5.0 the v1 tools always answered in English ("Solved") while the v2 ones answered in the GLPI language ("Solucionado").

The API v2 labels the status itself but sends priority, urgency, impact and the ticket type as numbers. Since 3.5.1 the v2 ticket/change/problem tools add priority_name, urgency_name, impact_name (and type_name on tickets) beside the codes, in the language whose status table matches the status labels the API returned (the v2 session carries no language); the timeline adds status_name to validations and solutions and state_name to tasks, with the language cached per credential (or read from one ticket). English when nothing matches.

glpi_search keys its rows by search option name in the GLPI user's language ("Título", "Status", "Última atualização") by default since 3.5.0; named_columns: false returns the numeric option IDs ("1", "12", "19"). Since 3.5.1 coded columns (status, priority, urgency, impact, ticket type, approval and solution-approval status) hold the label in the session language and the code sits beside it under "<name> (id)": "Status": "Solucionado", "Status (id)": 5. A column is labelled only when its search option points at a known table/field; the markdown table leaves the (id) columns out, and named_columns: false stays the raw search.

Full reference: docs/TOOLS.md (v1) and docs/v2/TOOLS.md (v2); OAuth2 setup in docs/v2/SETUP.md.

Toolsets

Named presets for GLPI_TOOLSETS (or the toolsets option of instanceFromConfig). Domain presets hold both families; a family still needs its credentials to register. A tool can be in more than one preset, and every tool is in at least one besides core (asserted by the tests). core is the lean default for hosted use: every read tool of the everyday presets (no webhook, rule or session internals) plus the non-destructive ticket operations.

Presets are self-contained (asserted by the tests): a tool named in another tool's description or parameters is in every preset that holds the tool naming it. That is why tickets carries glpi_search / glpi_list_search_options and the user/group reads that put names on people, and assets carries the generic search its list tool points to.

Administration with writes only in admin (3.5.0, owner's decision): creating or changing users and groups, entities, business rules and webhooks is not in core nor in any everyday preset (tickets, itil, assets, kb, documents, users, search); the reads that help with a ticket (users, groups, entities) stay. The v2 preset is the whole family and still holds them. Asserted by the tests (ADMIN_WRITE_TOOLS, EVERYDAY_TOOLSETS).

Before 3.5.0: users 15 (7 + 8), admin 42 (31 + 11). Before 3.4.0: core 92, tickets 42, itil 38, assets 13.

As a library

The package root exports the server factory; importing it never starts a transport (the stdio and HTTP servers are the mcp-glpi and mcp-glpi-http bins).

import { createGlpiServer, instanceFromConfig } from "@nextoolsolutions/mcp-glpi";
const instance = instanceFromConfig({  id: "acme",                                   // lowercase letters, digits, "-"  v1: { url: "https://glpi.acme.com", userToken, appToken },  v2: { url: "https://glpi.acme.com", clientId, clientSecret, username, password, scope: "api", apiVersion: "v2.2" },  policy: { readOnly: true, allowDelete: false }, // defaults: false / false / requireDeleteReason true  toolsets: ["core"],                           // or "tickets,kb"  toolsInclude: ["glpi_search"],                // globs, add to toolsets  toolsExclude: ["*delete*"],                   // globs, always win  fetchImpl,                                    // optional, see below});const { server, summary } = createGlpiServer(instance, { fetchImpl, idempotencyStore });await server.connect(transport);

instanceFromConfig never reads process.env and throws on an invalid id or URL, on unknown toolsets and when neither v1 nor v2 is given. instanceFromEnv(id, env) builds the same thing from GLPI_* variables. Also exported: SERVER_VERSION, the InstanceConfig / InstanceEnv / InstanceOptions types, TOOLSETS / TOOLSET_NAMES / parseToolsets, the error classes (GlpiHttpError, GlpiApiError, GlpiV2ApiError, GlpiRedirectError, GlpiPolicyError) and IdempotencyStore.

fetchImpl. Same call shape as fetch ((url, init) => Promise<Response>), used for every GLPI request: v1 session and calls, v2 token and calls, assets and webhooks. A host can inject one that validates the resolved IP. It always receives redirect: "manual".

Safety defaults

• Destructive tools are off unless GLPI_ALLOW_DELETE=true, and require a written reason.
• GLPI_READ_ONLY=true blocks every write before it reaches GLPI — set on customer instances.
• Every tool publishes MCP annotations derived from its name: title, readOnlyHint (reads), destructiveHint (delete/purge/remove), idempotentHint (reads, update_*/set_*, deletes) and openWorldHint: false.
• Redirects are never followed: a 3xx from GLPI becomes redirect not followed: <status> -> <host> (GlpiRedirectError), so session and OAuth headers never reach another host.
• The v2 client only talks to the GLPI_V2_URL origin; an absolute URL to any other host is refused before a request goes out.
• Repeating a create_/add_ call with identical arguments within 120s replays the first result (replayed: true) instead of creating a second record.

Payload

Read tools default to fields: "essential": GLPI's internal bookkeeping (SLA/OLA counters, delay statistics, HAL links; API v2 durations) is dropped and TinyMCE richtext is flattened to plain text. Pass fields: "all" for the raw payload.

format: "markdown" returns a table for listings and key: value lines for one item (long texts never cut there). The markdown is in the text block and in structuredContent ({ data: "<markdown>", format: "markdown", count, note }): clients that support structured results (Claude among them) give the model structuredContent, so a text-only rendering was ignored before 3.4.0. JSON stays the default.

Listing tables are compact (3.5.0): a raw ticket row has 22 columns, bare IDs among them, so each kind of listing has its own column set (src/markdown-views.ts):

The JSON result keeps every field, and fields: "all" draws every column in markdown too.

Instructions

The instructions sent in initialize are built from the tools the server actually registered: under a preset (or GLPI_TOOLS_EXCLUDE) they name only the tools present, and the areas they list are the ones a registered tool covers. DEFAULT_INSTRUCTIONS is the text for a server with every tool of both families; buildInstructions(tools, { v1, v2 }) builds it for any set; a host passes createGlpiServer(instance, { instructions }) to replace it.

Listings are bounded by count and by size:

• 25 items by default, at most 100 per call (GLPI_DEFAULT_PAGE_SIZE, GLPI_MAX_PAGE_SIZE; the ceiling was 200);
• texts longer than 300 characters are cut in listings (GLPI_LIST_TEXT_MAX_CHARS); open the item, or pass fields: "all", for the full text. Ticket history listings (timeline, followups, tasks, validations) are not cut;
• one answer stays under 50,000 characters (GLPI_MAX_RESPONSE_CHARS): a longer listing is trimmed from the end.

The note says what happened and how to get the next page, naming only the tool's own parameters (Next page: range=68-135. or Next page: start=33 limit=33.).

Item IDs are positive integers (a number or a string of digits; entity IDs may be 0). Anything else ("abc", "", -1, 1.5) fails input validation before any request: an invalid ID used to reach GLPI as /ITILCategory/abc, which answered with the first page of the collection.

Errors come back as isError with the GLPI message in the text and no structuredContent (validating clients checked it against the output schema and replaced the message with a schema error).

Layout

• src/lib.ts — library entry (package root): createGlpiServer, instanceFromConfig, types
• src/index.ts — stdio entry (one instance from the environment)
• src/http.ts — HTTP entry: authentication, instance binding, sessions, audit
• src/create-server.ts — builds the server for one instance: safety layers, families, resources
• src/instance.ts — instance config from env or object (credentials, policy, tool selection) and credential cache keys
• src/tools-v1.ts, src/tools-v2.ts — tool registration per family
• src/tool-filter.ts — selection rule (toolsets + GLPI_TOOLS_INCLUDE / GLPI_TOOLS_EXCLUDE)
• src/toolsets.ts — named presets (GLPI_TOOLSETS)
• src/glpi-client.ts — API v1 client (tickets, ITIL, users, KB, rules, timeline)
• src/glpi-v2-client.ts — API v2 client (OAuth2 password grant with token cache)
• src/assets-client.ts — assets, reservations, counting
• src/webhooks-client.ts — webhooks and delivery queue (GLPI 10.0.7+)
• src/ticket-lists.ts — glpi_list_tickets sorting/status filter and glpi_list_my_tickets
• src/names.ts — names next to IDs (cached lookups) and the code labels
• src/labels.ts — code labels per GLPI language and the session (user + language) cache
• src/markdown-views.ts — compact markdown columns per kind of listing
• src/instructions.ts — instructions built from the registered tools
• src/search-columns.ts — search option names for glpi_search (named_columns, default on) and labels of its coded columns
• src/ids.ts — item ID schema
• src/resources.ts, src/prompts.ts — MCP resources and prompts
• test/ — npm test (node --test, no extra dependency)

Shared infrastructure — HTTP transport with retry, write policy, payload formatting, pagination and idempotency — lives in @nextoolsolutions/mcp-glpi-core, declared as a semver dependency (^1.3.0).

Development

Inside this repo the core resolves to the sibling folder: the lockfile links node_modules/@nextoolsolutions/mcp-glpi-core to ../mcp-glpi-core, and npm accepts the link because the folder's version satisfies ^1.3.0. So build the core first:

(cd ../mcp-glpi-core && npm ci && npm run build)   # the server loads the core's dist/npm cinpm testnpx tsc --noEmitnpx tsx src/index.ts     # needs GLPI_URL/GLPI_USER_TOKEN and/or the GLPI_V2_* variables

• After editing mcp-glpi-core, rebuild it (npm run build there).
• When the change needs a new core version, bump the core first, then the range here, then run npm install (it keeps the link and updates the lockfile).
• If the core folder's version does not satisfy the range, npm ci falls back to the npm registry. To link by hand: npm install ../mcp-glpi-core --no-save (or npm link).
• Release order: publish @nextoolsolutions/mcp-glpi-core first, then this package.