Topdesk

This MCP server exposes TOPdesk functionality to MCP clients by translating requests to the TOPdesk API through the TOPdeskPy SDK. It lets you manage TOPdesk incidents, people, operators, and more from any MCP client using a single, consistent interface, while handling authentication and API interactions under the hood.

How to use

You connect to this server from your MCP client as you would with any other MCP service. The server runs locally or on a chosen host and port, and it presents a standard MCP interface that your client can query to perform operations such as creating incidents, retrieving incident details, attaching files, and managing user requests.

To begin, start the MCP server in a way that your client can reach it. You will provide your TOPdesk instance URL, a user (API token) and the associated password or token in the environment. Your MCP client then calls the exposed MCP endpoints to interact with TOPdesk, without needing to handle TOPdesk authentication or API specifics directly.

How to install

Prerequisites you need before installing: a supported Python runtime (Python 3.11+). Ensure you have network access to install dependencies and run the MCP server.

# 1) Create and activate a Python virtual environment
python3.11 -m venv venv
source venv/bin/activate

# 2) Install the MCP server package in editable mode
pip install uv
pip install -e .

# 3) Install development dependencies (if you want dev tools and tests)
pip install -e ".[dev]"

4. Run the MCP server entry point to start listening and handling MCP requests.

python -m topdesk_mcp.main

Additional sections

Configuration details: The server expects TOPdesk connection information via environment variables. The following variables configure the TOPdesk API access and optional conversion features for attachments:

• TOPDESK_URL: Base URL of your TOPdesk instance.
• TOPDESK_USERNAME: Username associated with the API token.
• TOPDESK_PASSWORD: API token for authentication.
• Optional transport and host/port settings for MCP transport methods like stdio, streamable-http, or sse:
• TOPDESK_MCP_TRANSPORT
• TOPDESK_MCP_HOST
• TOPDESK_MCP_PORT
• Optional attachment conversion to Markdown settings for document conversion (Docling/OpenAI).
• DOCLING_ADDRESS
• DOCLING_API_KEY
• DOCLING_USERNAME
• DOCLING_PASSWORD
• OPENAI_API_BASE
• OPENAI_API_KEY
• OPENAI_MODEL_NAME
• SSL_VERIFY These variables let you customize how TOPdesk data is retrieved and how attachments are processed for Markdown output.

For local development, a typical runtime configuration places the MCP server under a local process and exposes it via a standard IO interface. A sample configuration snippet shows how the MCP server is wired to the runtime environment.

{
  "servers": {
    "topdesk-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "topdesk-mcp"
      ],
      "env": {
         "TOPDESK_URL": "<your topdesk URL>",
         "TOPDESK_USERNAME": "<your topdesk username>",
         "TOPDESK_PASSWORD": "<your topdesk api key>"
      }
    }
  }
}

Available tools

topdesk_get_fiql_query_howto

Get a hint on how to construct FIQL queries, with examples.

topdesk_get_object_schemas

Get the full object schemas for TOPdesk incidents and all their subfields.

topdesk_get_incident

Get a TOPdesk incident by UUID or by Incident Number.

topdesk_get_incidents_by_fiql_query

Get TOPdesk incidents by FIQL query.

topdesk_get_incident_user_requests

Get all user requests on a TOPdesk incident.

topdesk_create_incident

Create a new TOPdesk incident.

topdesk_archive_incident

Archive a TOPdesk incident.

topdesk_unarchive_incident

Unarchive a TOPdesk incident.

topdesk_get_timespent_on_incident

Get all time spent entries for a TOPdesk incident.

topdesk_register_timespent_on_incident

Register time spent on a TOPdesk incident.

topdesk_escalate_incident

Escalate a TOPdesk incident.

topdesk_get_available_escalation_reasons

Get all available escalation reasons for a TOPdesk incident.

topdesk_get_available_deescalation_reasons

Get all available de-escalation reasons for a TOPdesk incident.

topdesk_deescalate_incident

De-escalate a TOPdesk incident.

topdesk_get_progress_trail

Get the progress trail for a TOPdesk incident.

topdesk_get_incident_attachments

Get all attachments for a TOPdesk incident as base64-encoded data.

topdesk_get_incident_attachments_as_markdown

Download and convert all attachments for a TOPdesk incident to Markdown format using intelligent document conversion.

topdesk_get_complete_incident_overview

Get a comprehensive overview of a TOPdesk incident including details, progress, and Markdown attachments.

topdesk_get_operatorgroups_of_operator

Get operator groups that an operator belongs to.

topdesk_get_operator

Get a TOPdesk operator by ID.

topdesk_get_operators_by_fiql_query

Get TOPdesk operators by FIQL query.

topdesk_add_action_to_incident

Add a comment or action to a TOPdesk incident.

topdesk_get_incident_actions

Get all actions for a TOPdesk incident.

topdesk_delete_incident_action

Delete a specific action from a TOPdesk incident.

topdesk_get_person_by_query

Get TOPdesk persons by FIQL query.

topdesk_get_person

Get a TOPdesk person by ID.

topdesk_create_person

Create a new TOPdesk person.

topdesk_update_person

Update an existing TOPdesk person.

topdesk_archive_person

Archive a TOPdesk person.

topdesk_unarchive_person

Unarchive a TOPdesk person.