i-net HelpDesk MCP Server

i-net HelpDesk の チケットWeb API を任意のAIエージェント向けツールとして提供する MCP サーバーです。チケットの検索・閲覧、処理ステップの確認、新規チケット作成、チケットアクション（返信、クローズ、エスカレーションなど）の実行が可能で、ファイル添付にも対応しています。

サーバーは2つの方法で運用できます。

前提条件

• 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認証）も使用できます。トークンは 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を入力し、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を使用したリバースプロキシを配置してください。

ツール

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。ファイルあたりの上限: 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 で適切に制限してください。

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