i-net HelpDesk MCP Server

An MCP server that provides the Ticket Web API of i-net HelpDesk as tools for any AI agent: search and read tickets, view processing steps, create new tickets, and execute ticket actions (reply, close, escalate ...) — including file attachments.

The server can be operated in two ways:

Requirements

• Python 3.10 or newer

• An i-net HelpDesk with activated Web API

• A user with the right "Web API" — without this right, the server responds with HTTP 403. Which tickets are visible and which actions are allowed depends on the roles of this user.

Related MCP server: tickiti-mcp

Installation

# direkt aus dem Repository ausführen (empfohlen für den Einstieg)
uvx --from git+https://github.com/roddyst/i-net_mcp_server inet-helpdesk-mcp --help

# oder klassisch installieren
pip install git+https://github.com/roddyst/i-net_mcp_server

For development:

git clone https://github.com/roddyst/i-net_mcp_server
cd i-net_mcp_server
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest

Quickstart: stdio (local agent)

export INET_BASE_URL="https://helpdesk.example.com:9000"
export INET_TOKEN="VGhpcyBpcyBqdXN0IGEgZGVtbyBhY2Nlc3MgdG9rZW4u"
inet-helpdesk-mcp

Configuration for Claude Desktop / Claude Code (claude_desktop_config.json or .mcp.json) — more examples are in examples/:

{
  "mcpServers": {
    "i-net-helpdesk": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/roddyst/i-net_mcp_server", "inet-helpdesk-mcp"],
      "env": {
        "INET_BASE_URL": "https://helpdesk.example.com:9000",
        "INET_TOKEN": "dein-access-token"
      }
    }
  }
}

Instead of a token, INET_USERNAME and INET_PASSWORD (Basic Auth) also work. The token is sent as Authorization: Bearer <token>, exactly as described in the i-net documentation.

Quickstart: HTTP (centrally hosted)

inet-helpdesk-mcp --transport http --host 0.0.0.0 --port 8000 \
                  --base-url https://helpdesk.example.com:9000

The endpoint is then at http://<host>:8000/mcp. The agent enters this URL and sends its HelpDesk token in the Authorization header — this is exactly the "URL + Bearer Token" process; the server forwards the header to the HelpDesk. Example for an MCP client that supports remote servers:

{
  "mcpServers": {
    "i-net-helpdesk": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer dein-access-token" }
    }
  }
}

Without --base-url, the client additionally determines the target system via the X-Inet-Base-Url header. This is practical for tenants with multiple HelpDesk instances but opens the server as a proxy for arbitrary addresses — in an open network, it is therefore better to set a fixed --base-url (then the header is disabled, unless it is allowed with --allow-url-header).

Note on operation: The server does not terminate TLS itself and does not authenticate clients independently — login happens at the HelpDesk with the passed-through token. If it is to be accessible beyond the local network, a reverse proxy with HTTPS should be placed in front of it.

Tools

create_ticket and apply_ticket_action are not registered at all with --read-only — useful if an agent should only be able to read.

Ticket IDs are accepted both as numbers and in the encoded form that appears in the subject lines of HelpDesk emails.

Typical workflow

1. search_tickets with a phrase like Drucker or Resource:"First Level Support"

2. get_ticket / list_ticket_steps / get_ticket_step to read

3. list_ticket_actions to determine the valid action_id

4. apply_ticket_action with this ID — the IDs differ per ticket, user, and ticket status, so they must not be guessed.

Ticket fields and action arguments

ticket_fields, step_fields, and action_arguments are optional and are normally not needed. If they are, the rules of the Web API apply: keys must correspond to real field keys (or their localized display names), values are strings; JSON values must be encoded as strings. Examples from the i-net documentation:

{
  "ticketextension.dispatchNow": "ALWAYS",           // Ticket sofort disponieren
  "ticketextension.automail": "NO_MAILS_TO_ENDUSER", // keine Auto-Mails an Endanwender
  "processingtimeextension.appointment": "1733875200000", // Wiedervorlage/Termin
  "ticketactionextension.escalate": "{'targetResID':'<GUID>','changeTicketStatus':true}"
}

Unknown ticket fields lead to an error; unknown action arguments are silently discarded by the HelpDesk and only written to the debug log.

Attachments

Attachments are passed as a list, each with content either inline as Base64 or as a path on the server's file system:

{
  "text": "Anfrage mit Anhang",
  "attachments": [
    { "name": "screenshot.png", "content_base64": "iVBORw0KGgo…" },
    { "path": "/tmp/protokoll.pdf", "attachment_type": "Attachment" }
  ]
}

path only works in stdio mode, where the agent and server share the same machine; in HTTP modes it is automatically disabled (and can also be disabled for stdio with --no-local-files). Allowed values for attachment_type: Attachment, EmbeddedImage, Signature, Unknown. Maximum per file: 25 MB.

Configuration

Every option is available as an environment variable and as a command-line switch; the command line wins.

Troubleshooting

• Call server_info first — it shows the base URL, auth method, and whether a test query against the HelpDesk works.

• HTTP 401/403: Token expired or the user lacks the "Web API" right.

• HTTP 404 for a ticket: Ticket does not exist or is not visible to this user; tickets that are not yet authorized require the dispatcher role.

• Connection errors: Check the base URL including the port (the HelpDesk default is 9000). For self-signed test systems, --no-verify-tls helps.

• More details are provided by --log-level DEBUG (logs go to stderr).

Security notes

• Credentials are stored in environment variables or in the Authorization header and are never logged.

• The server does exactly what the logged-in user is allowed to do — the rights check remains with the HelpDesk.

• apply_ticket_action and create_ticket modify data and can, depending on the configuration, trigger emails to end users. For tests, the action argument "ticketextension.automail": "NEVER" or a test system is recommended.

• get_ticket by default returns all fields of a ticket, including personal data — restrict it deliberately with fields.

English summary

MCP server exposing the i-net HelpDesk Ticket Web-API: search, read, create and act on tickets, with attachment support. Run it over stdio (credentials from INET_BASE_URL + INET_TOKEN) or over streamable HTTP, where each client authenticates by sending its own Authorization: Bearer <token> header — and, when no base URL is configured, selects the HelpDesk instance with an X-Inet-Base-Url header. Tools: server_info, search_tickets, get_ticket, list_ticket_actions, list_ticket_steps, get_ticket_step, create_ticket, apply_ticket_action. Start with --read-only to expose the reading tools only.

License

MIT. Not an official product of i-net software GmbH. Web API documentation: https://docs.inetsoftware.de/helpdesk/help/webapi.ticket/p/ticket-web-api