i-net HelpDesk MCP 서버

i-net HelpDesk의 Ticket-Web-API를 모든 AI 에이전트를 위한 도구로 제공하는 MCP 서버입니다: 티켓 검색 및 읽기, 처리 단계 보기, 새 티켓 생성, 티켓 작업(답변, 종료, 에스컬레이션 등) 실행 — 파일 첨부 포함.

서버는 두 가지 방식으로 운영할 수 있습니다:

전제 조건

• 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(Basic Auth)도 사용할 수 있습니다. 토큰은 i-net 문서에 설명된 대로 Authorization: Bearer <token>으로 전송됩니다.

빠른 시작: 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을 입력하고 HelpDesk 토큰을 Authorization 헤더에 담아 보냅니다 — 이것이 바로 "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를 사용하는 리버스 프록시를 두어야 합니다.

도구

create_ticket와 apply_ticket_action은 --read-only를 사용하면 등록되지 않습니다 — 에이전트가 읽기만 가능해야 할 때 유용합니다.

티켓 ID는 숫자와 HelpDesk 이메일 제목 줄에 있는 인코딩된 형식 모두 허용됩니다.

일반적인 흐름

1. search_tickets로 Drucker 또는 Resource:"First Level Support" 같은 구문 검색

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. 파일당 최대 크기: 25MB.

구성

모든 옵션은 환경 변수와 명령줄 스위치로 제공됩니다. 명령줄이 우선합니다.

문제 해결

• 먼저 server_info 호출 — 기본 URL, 인증 방식, HelpDesk에 대한 테스트 쿼리 작동 여부를 표시합니다.

• HTTP 401/403: 토큰이 만료되었거나 사용자에게 "Web API" 권한이 없습니다.

• 티켓에서 HTTP 404: 티켓이 존재하지 않거나 해당 사용자에게 표시되지 않습니다. 아직 승인되지 않은 티켓은 Dispatcher 역할이 필요합니다.

• 연결 오류: 포트를 포함한 기본 URL 확인(HelpDesk 기본값은 9000). 자체 서명된 테스트 시스템에서는 --no-verify-tls가 도움이 됩니다.

• 더 자세한 내용은 --log-level DEBUG(로그는 stderr로 출력).

보안 참고 사항

• 자격 증명은 환경 변수 또는 Authorization 헤더에 있으며 절대 로깅되지 않습니다.

• 서버는 로그인한 사용자가 허용하는 작업만 수행합니다 — 권한 확인은 HelpDesk에 남아 있습니다.

• apply_ticket_action과 create_ticket은 데이터를 변경하며 구성에 따라 최종 사용자에게 이메일을 보낼 수 있습니다. 테스트에는 작업 인수 "ticketextension.automail": "NEVER" 또는 테스트 시스템을 사용하는 것이 좋습니다.

• get_ticket은 기본적으로 개인 데이터를 포함한 모든 티켓 필드를 반환합니다 — 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.

라이선스

MIT. i-net software GmbH의 공식 제품이 아닙니다. Web-API 문서: https://docs.inetsoftware.de/helpdesk/help/webapi.ticket/p/ticket-web-api