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": "",
         "TOPDESK_USERNAME": "",
         "TOPDESK_PASSWORD": ""
      }
    }
  }
}

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.