topdesk-mcp

This project is a Model Context Protocol (MCP) server implemented in Python. It exposes the Topdesk API via the TOPdeskPy SDK.

Project Purpose

• Acts as an MCP server to bridge MCP clients with the Topdesk API.
• Uses the TOPdeskPy SDK (with some modifications) for all Topdesk API interactions.

MCP Config JSON

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

Environment Variables

• TOPDESK_URL: The base URL of your Topdesk instance. e.g. https://yourcompany.topdesk.net
• TOPDESK_USERNAME: The username you generated the API token against.
• TOPDESK_PASSWORD: Your API token
• TOPDESK_MCP_TRANSPORT: (Optional) The transport to use: 'stdio', 'streamable-http', 'sse'. Defaults to 'stdio'.
• TOPDESK_MCP_HOST: (Optional) The host to listen on (for 'streamable-http' and 'sse'). Defaults to '0.0.0.0'.
• TOPDESK_MCP_PORT: (Optional) The port to listen on (for 'streamable-http' and 'sse'). Defaults to '3030'.

Document Conversion Environment Variables

Topdesk Attachments can be converted to Markdown format by the tool.

By default it will try to do this with simple MarkItDown library which often isn't sufficient.

These variables configure the attachment-to-markdown conversion feature to leverage a Docling or OpenAI instance instead:

• DOCLING_ADDRESS: (Optional) URL of a Docling API server for document conversion. e.g. http://localhost:8080
• DOCLING_API_KEY: (Optional) API key for Docling API authentication
• DOCLING_USERNAME: (Optional) Username for Docling API basic authentication (fallback if no API key)
• DOCLING_PASSWORD: (Optional) Password for Docling API basic authentication (fallback if no API key)
• OPENAI_API_BASE: (Optional) Base URL for OpenAI-compatible API for document conversion. e.g. https://api.openai.com
• OPENAI_API_KEY: (Optional) API key for OpenAI API authentication
• OPENAI_MODEL_NAME: (Optional) Model name to use for OpenAI API calls. Defaults to 'gpt-4.1'
• SSL_VERIFY: (Optional) Enable/disable SSL verification for API calls. Set to 'false' to disable. Defaults to 'true'.

Setup for Local Development

1. Ensure Python 3.11+ is installed.

2. Create and activate a virtual environment:

   pip install uv
   uv venv
   uv pip install -e .
   uv pip install -e ".[dev]"
   

3. Run:

   python -m topdesk_mcp.main
   

Notes:

• The server skeleton was generated using the official MCP server template.
• Contributions are welcome.

Publishing

Every push to master, including merged pull requests, builds and publishes to PyPI using the existing trusted publisher for .github/workflows/pypi.yml. Release Please and RELEASE_PLEASE_TOKEN are no longer used.

The published version uses the major/minor version from pyproject.toml, with its patch number plus the publishing workflow's run number. For example, base version 0.8.1 and run number 21 publish 0.8.22. The base version stays in the repository; publishing does not create version-bump commits. Keep the base version stable within a major/minor series so subsequent versions increase. Retries retain the same version and skip files already uploaded to PyPI.

After a successful PyPI publish, the workflow creates a GitHub release and a v<version> tag pointing to the published commit (for example, v0.8.22). GitHub automatically generates the release changelog since the previous release, including merged pull requests, contributors, and a link to the full comparison. For the first release, GitHub generates notes from the available history. Retries skip an existing GitHub release for the same version.

Package Structure

topdesk_mcp/  # Directory for the MCP server package
    __init__.py     # Marks as a Python package
    main.py         # Entry point for the MCP server
    
    _topdesk_sdk.py # TOPdeskPy SDK
    _incident.py    # Incidents API
    _operator.py    # Operator API
    _person.py      # Person API
    _utils.py       # Helper methods for Requests

    tests/
      (unit tests)

Exposed 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 (I-xxxxxx-xxx). Both formats are accepted.

• 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. Uses intelligent document conversion with support for PDFs, Office documents, images, and other file types. Attempts conversion using OpenAI API (if configured), then Docling API (if configured), and falls back to MarkItDown for local processing.

• topdesk_get_complete_incident_overview
  Get a comprehensive overview of a TOPdesk incident including its details, progress trail, and attachments converted to Markdown. This tool combines the results of topdesk_get_incident, topdesk_get_progress_trail, and topdesk_get_incident_attachments_as_markdown into a single response for convenient access to all incident information.

• topdesk_get_operatorgroups_of_operator
  Get a list of TOPdesk operator groups that an op is a member of, optionally by FIQL query or leave blank to return all groups.

• 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 an action (ie, reply/comment) to a TOPdesk incident.

• topdesk_get_incident_actions
  Get all actions (ie, replies/comments) for a TOPdesk incident.

• topdesk_delete_incident_action
  Delete a specific action (ie, reply/comment) for 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.

References

• MCP Protocol Documentation
• TOPdeskPy SDK
• FastMCP

License

MIT license.