i-net HelpDesk MCP 服务器

一个 MCP 服务器，将 i-net HelpDesk 的工单 Web API 作为工具提供给任意 AI 代理使用：搜索和读取工单、查看处理步骤、创建新工单以及执行工单操作（回复、关闭、升级等）——包括文件附件。

该服务器可通过两种方式运行：

前提条件

• Python 3.10 或更高版本

• 一个启用了 Web API 的 i-net HelpDesk

• 一个拥有 “Web API” 权限的用户——没有此权限，服务器将返回 HTTP 403。哪些工单可见以及允许哪些操作，取决于该用户的角色。

Related MCP server: tickiti-mcp

安装

# 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

用于开发：

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

快速入门：stdio（本地代理）

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

Claude Desktop / Claude Code 的配置（claude_desktop_config.json 或 .mcp.json）——更多示例位于 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"
      }
    }
  }
}

除了令牌，也可以使用 INET_USERNAME 和 INET_PASSWORD（基本身份验证）。令牌作为 Authorization: Bearer <token> 发送，与 i-net 文档中描述的方式完全相同。

快速入门：HTTP（集中托管）

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

端点位于 http://<host>:8000/mcp。代理输入此 URL 并在 Authorization 标头中发送其 HelpDesk 令牌——这正是“URL + Bearer 令牌”的流程，服务器将该标头转发给 HelpDesk。支持远程服务器的 MCP 客户端示例：

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

如果没有 --base-url，客户端还会通过 X-Inet-Base-Url 标头确定目标系统。这对于拥有多个 HelpDesk 实例的租户来说很方便，但会将服务器作为任意地址的代理打开——因此在开放网络中，最好设置一个固定的 --base-url（这样该标头将被禁用，除非使用 --allow-url-header 允许）。

运行提示： 服务器自身不终止 TLS 也不独立验证客户端——登录是通过传递的令牌在 HelpDesk 上完成的。如果它需要在本地网络之外可访问，则需要在前面放置一个带有 HTTPS 的反向代理。

工具

使用 --read-only 时，create_ticket 和 apply_ticket_action 根本不会被注册——当代理只需要读取权限时很有用。

工单 ID 可以以数字形式接受，也可以以 HelpDesk 电子邮件主题行中出现的编码形式接受。

典型流程

1. 使用类似 Drucker 或 Resource:"First Level Support" 的短语调用 search_tickets

2. 调用 get_ticket / list_ticket_steps / get_ticket_step 进行读取

3. 调用 list_ticket_actions 以确定有效的 action_id

4. 使用该 ID 调用 apply_ticket_action——ID 因工单、用户和工单状态而异，因此不能猜测。

工单字段和操作参数

ticket_fields、step_fields 和 action_arguments 是可选的，通常不需要。如果需要，则遵循 Web API 的规则：键必须对应真实的字段键（或其本地化的显示名称），值是字符串；JSON 值必须编码为字符串。来自 i-net 文档的示例：

{
  "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}"
}

未知的 工单字段 会导致错误，未知的 操作参数 会被 HelpDesk 静默丢弃，仅写入调试日志。

附件

附件作为列表传递，每个附件的内容 要么 内联为 Base64 要么 作为服务器文件系统上的路径：

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

path 仅在 stdio 模式下有效，在该模式下代理和服务器共享同一台机器；在 HTTP 模式下它会自动禁用（并且可以使用 --no-local-files 为 stdio 也禁用它）。attachment_type 的允许值：Attachment、EmbeddedImage、Signature、Unknown。每个文件的上限：25 MB。

配置

每个选项都可以作为环境变量和命令行开关使用；命令行优先级更高。

故障排除

• 首先调用 server_info——它会显示基础 URL、身份验证方法以及针对 HelpDesk 的测试查询是否有效。

• HTTP 401/403：令牌已过期或用户缺少“Web API”权限。

• 工单的 HTTP 404：工单不存在或对该用户不可见；尚未授权的工单需要调度员角色。

• 连接错误：检查包含端口的基础 URL（HelpDesk 的默认端口是 9000）。对于自签名的测试系统，--no-verify-tls 会有所帮助。

• 更多详细信息请使用 --log-level DEBUG（日志输出到 stderr）。

安全说明

• 凭据位于环境变量或 Authorization 标头中，永远不会被记录。

• 服务器只执行登录用户被允许的操作——权限检查由 HelpDesk 负责。

• apply_ticket_action 和 create_ticket 会修改数据，并且根据配置可能会触发发送给最终用户的电子邮件。对于测试，建议使用操作参数 "ticketextension.automail": "NEVER" 或使用测试系统。

• get_ticket 默认返回工单的所有字段，包括个人数据——使用 fields 进行针对性限制。

英文摘要

暴露 i-net HelpDesk 工单 Web API 的 MCP 服务器：搜索、读取、创建和处理工单，支持附件。通过 stdio（凭据来自 INET_BASE_URL + INET_TOKEN）或通过 可流式 HTTP 运行，每个客户端通过发送自己的 Authorization: Bearer <token> 标头进行身份验证——并且，当未配置基础 URL 时，通过 X-Inet-Base-Url 标头选择 HelpDesk 实例。工具：server_info、search_tickets、get_ticket、list_ticket_actions、list_ticket_steps、get_ticket_step、create_ticket、apply_ticket_action。使用 --read-only 启动以仅暴露读取工具。

许可证

MIT。非 i-net software GmbH 的官方产品。 Web API 文档： https://docs.inetsoftware.de/helpdesk/help/webapi.ticket/p/ticket-web-api