dbsanfte/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
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:
4. Run:
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.
Package Structure
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.