freeitsm-mcp-server

A standalone MCP server that lets an AI assistant work with FreeITSM through its REST API (/api/v1): search, read, create and update tickets, changes, problems, knowledge, assets and everything else the API offers (285 endpoints as of FreeITSM 4.12).

The API key is the security boundary. The server is a plain API client: what the key may do (its permissions, company scope, expiry, rate limit and the analyst it acts as) is all the assistant may do. FreeITSM enforces this on every request. On top of that, the server:

• asks FreeITSM at startup what the key may do (GET /api/v1/ping) and offers only the tools that key can use - a ticket-read key never sees a write tool;

• checks each call against the key's permissions before sending it, and says which permission is missing;

• can run read-only (FREEITSM_READ_ONLY=true) whatever the key allows.

It is separate from FreeITSM's built-in MCP endpoint (/api/mcp/), which is read-only and offers a fixed set of summary tools. This one covers the whole REST API, including writes.

Requirements

• Node.js 20.12 or later, or Docker (see Docker)

• A FreeITSM install with the REST API, and an API key from System > API with the permissions you want the assistant to have. A dedicated analyst (e.g. "AI Assistant") keeps the audit trail readable.

Related MCP server: Freshservice MCP Server

Setup

git clone <this repository> freeitsm-mcp
cd freeitsm-mcp
npm install        # also builds dist/

Register it with your MCP client as a stdio server: the command is node, the argument is the full path to dist/index.js, and the settings are environment variables. Most clients take a JSON entry of this shape:

{
  "mcpServers": {
    "freeitsm-api": {
      "command": "node",
      "args": ["/path/to/freeitsm-mcp/dist/index.js"],
      "env": {
        "FREEITSM_URL": "https://itsm.example.com",
        "FREEITSM_API_KEY": "fitsm_xxx",
        "FREEITSM_READ_ONLY": "true"
      }
    }
  }
}

The tool list is fixed when the server starts. After changing the key's permissions, restart the server. The startup line on stderr says which key it uses, how many endpoints it may call, and whether it is READ-ONLY or WRITABLE.

Docker

The image is built from pinned base images. It runs on a distroless Node runtime (no shell, no package manager) as a non-root user, and holds only production dependencies. The server's files are owned by root, so the process cannot modify its own code.

docker build -t freeitsm-mcp-server .

The server speaks MCP over stdio, so the client starts the container itself and keeps stdin open (-i). Recommended entry, locked down:

{
  "mcpServers": {
    "freeitsm-api": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--read-only", "--cap-drop=ALL", "--security-opt=no-new-privileges",
        "--memory=256m", "--pids-limit=64",
        "-e", "FREEITSM_URL", "-e", "FREEITSM_API_KEY", "-e", "FREEITSM_READ_ONLY",
        "freeitsm-mcp-server"
      ],
      "env": {
        "FREEITSM_URL": "https://itsm.example.com",
        "FREEITSM_API_KEY": "fitsm_xxx",
        "FREEITSM_READ_ONLY": "true"
      }
    }
  }
}

• -e NAME without a value copies the variable from the client's environment, so the key is not written on the docker command line (which other local users could see in the process list).

• The server needs no writable filesystem, so --read-only works as-is.

• Uploads: mount the folder read-only and point the variable at the mount, e.g. add "-v", "/path/to/evidence:/uploads:ro", "-e", "FREEITSM_UPLOAD_DIR=/uploads".

• FreeITSM on the same machine: inside the container localhost is the container itself. Use http://host.docker.internal:<port> (on Linux also add "--add-host=host.docker.internal:host-gateway"). The server will warn that this is plain http, which is fine for a local install. Use https for anything remote.

• To restrict network access further, attach the container to a Docker network that can reach only the FreeITSM host.

Tools

Dedicated tools (each appears only if the key has the permission it needs):

Generic tools, covering every endpoint:

The endpoint catalogue is read at startup from the install's own /api/v1/openapi.json and /api/v1/spec.json, so it matches the FreeITSM version you connect to. An endpoint whose required permission cannot be determined is treated as unavailable.

Security notes

• Give the key only what the assistant needs. The local filtering above is a convenience and a second line of defence; the key's permissions in FreeITSM are what actually protect your data. Start with a read-only key or FREEITSM_READ_ONLY=true.

• Records contain other people's text. Ticket bodies, emails and articles can include instructions aimed at an AI ("ignore your rules and ..."). An assistant with write access could be talked into acting on them. Keep write access narrow, and use an MCP client that asks before running write tools (they are annotated as such).

• Local files. Only files inside FREEITSM_UPLOAD_DIR can be uploaded (symlinks are resolved first), so an assistant cannot be steered into uploading, say, SSH keys. Leave it unset unless you need it.

• Paths are checked strictly. The generic tools accept only plain API paths (no .., percent-encoding or backslashes), so the endpoint that is checked is the endpoint that is called. Redirects are never followed, so the key is only ever sent to FREEITSM_URL.

Development

npm test            # builds, then runs unit and in-process tests with a stubbed FreeITSM
npm run typecheck   # src, tests and scripts
npm run smoke       # read-only checks against a real install; settings in .env (see .env.example)
npm run fixtures    # refresh test/fixtures from FREEITSM_URL
npx @modelcontextprotocol/inspector node dist/index.js   # interactive

Licence and credits

MIT - see LICENSE.

FreeITSM is by Ed Mozley and is also MIT-licensed. The files in test/fixtures/ are FreeITSM's own API description documents, generated by a FreeITSM install, and are included for testing under its licence.