ServiceDesk Plus Model Context Protocol (MCP) Server

A production-ready Model Context Protocol (MCP) server that connects large language models (LLMs) securely with your ManageEngine ServiceDesk Plus (On-Premise / Self-Hosted) instance. This server allows AI agents (such as Claude Desktop, Cursor, and other MCP hosts) to query, search, create, update, and manage help desk tickets and technical notes in real-time.

---

🛠️ Features

• List & Search Tickets: Rich server-side filtering by status, requester email, and advanced subject-contains keyword queries.
• Get Ticket Details: Retrieve comprehensive information on a single ticket, including its subject, description, priority, and resolution content.
• Create Tickets: Seamlessly open new help desk requests with custom subjects, HTML/plain-text descriptions, and priorities.
• Update Tickets: Real-time updates to ticket statuses, descriptions, and subjects.
• Manage Technical Notes: Exposes tools to list and append technical updates directly onto tickets.
• Public & Secure: Rigorously designed for open-source safety. Zero hardcoded secrets, domains, or credentials.
• Classic UI Integration: Automatically generates browser-viewable deep links tailored for the Classic UI layout.
• Complete Offline Testing: Includes a 100% offline unit test suite with mock network interception (respx).

---

📐 Architecture Overview

 ┌─────────────────┐             ┌────────────────────┐             ┌─────────────────────┐
 │                 │    Stdio    │                    │    HTTPS    │  ManageEngine       │
 │    MCP Host     │  ─────────> │  servicedesk-plus  │  ─────────> │  ServiceDesk Plus   │
 │ (e.g. Claude)   │  <───────── │     (MCP Server)   │  <───────── │  (On-Premise API)   │
 │                 │             │                    │ (authtoken) │                     │
 └─────────────────┘             └────────────────────┘             └─────────────────────┘

---

📋 MCP Tools Exposed

This server exposes 6 robust tools to the AI client:

Tool Name	Parameters	Description
list_tickets	status (opt), requester_email (opt), search_query (opt), row_count (opt), start_index (opt)	Retrieve, paginated, and filter tickets. Performs efficient server-side query filtering.
get_ticket	ticket_id (req)	Retrieve full details of a single ticket (including HTML description and resolutions).
create_ticket	subject (req), description (req), priority (opt), requester_email (opt)	Create a new help desk request.
update_ticket	ticket_id (req), subject (opt), description (opt), status (opt)	Update fields on an existing ticket.
add_ticket_note	ticket_id (req), note (req)	Append a technical log or update note to a ticket.
list_ticket_notes	ticket_id (req)	Fetch all technical notes logged on a specific ticket.

---

🚀 Quick Start

Prerequisites

• Python 3.10 or higher.
• uv is highly recommended for lightning-fast package and tool management (or standard pip).

1. Configure Your Credentials

Copy the .env.example template to .env:

cp .env.example .env

Open .env and fill in your details:

SDP_API_KEY=your_technician_key_here
SDP_BASE_URL=productsupport.example.com
SDP_USERNAME=your_username_here

Note: Your SDP_API_KEY (Technician Key/Authtoken) is generated from your ServiceDesk Plus profile page.

---

📦 Local Installation & Build

Building the Package

You can build a clean local package artifact (wheel file) of the server using standard build tools:

Using uv:

uv build

Using standard Python:

python -m pip install --upgrade build
python -m build

This will compile and output the package to dist/servicedesk_plus-0.1.0-py3-none-any.whl.

---

🔌 Configuring Your MCP Host

1. Claude Desktop

Add this to your claude_desktop_config.json (typically located in %APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Option A: Running from Built Local Wheel (Recommended)

This approach executes the server inside an isolated temporary sandbox with standard uvx:

{
  "mcpServers": {
    "servicedesk-plus": {
      "command": "uvx",
      "args": [
        "--from",
        "C:\\Workspace\\google-cli\\productsupport-mcp\\dist\\servicedesk_plus-0.1.0-py3-none-any.whl",
        "servicedesk-plus"
      ],
      "env": {
        "SDP_API_KEY": "YOUR_API_KEY",
        "SDP_BASE_URL": "productsupport.example.com",
        "SDP_USERNAME": "your_email@domain.com"
      }
    }
  }
}

Option B: Running from Local Sources (Development)

{
  "mcpServers": {
    "servicedesk-plus": {
      "command": "C:\\Workspace\\google-cli\\productsupport-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Workspace\\google-cli\\productsupport-mcp\\src\\servicedesk_plus\\main.py"
      ],
      "env": {
        "SDP_API_KEY": "YOUR_API_KEY",
        "SDP_BASE_URL": "productsupport.example.com",
        "SDP_USERNAME": "your_email@domain.com"
      }
    }
  }
}

---

🧪 Running Unit Tests

This project includes a comprehensive offline unit testing suite utilizing pytest and respx to mock ServiceDesk Plus API responses entirely.

1. Install development requirements in your virtual environment:

   pip install -e .[dev]
   

2. Run tests:

   pytest
   

All tests run 100% offline, allowing verification of tool registration, query formatting, body payload construction, and response unpacking with zero credentials or internet required.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.