deskpro-mcp

Deskpro MCP Server

A PHP MCP (Model Context Protocol) server for Deskpro helpdesk, built on the Enchilada Framework.

Provides ticket management, search, and agent tools via the MCP stdio transport - including OAuth Bearer token authentication with automatic refresh, which is not available through the standard API key method alone.

Features

• 22 tools for complete helpdesk management from an AI assistant
• Ticket operations - get, create, update, search, list with pagination and filters
• Agent actions - reply, internal note, assign, change status, view messages
• Lookups - departments, agents, statuses, custom fields, saved filters
• Self-documenting - built-in help, tool categories, usage examples, error guide
• Dual authentication - API Key or OAuth Bearer token with automatic refresh
• Multi-instance - manage multiple Deskpro helpdesks from a single server
• Zero dependencies - no Composer, no npm; just PHP 8.2+ with curl and json
• PHAR distribution - single-file deployment (~97 KB)

Requirements

• PHP 8.2 or later
• PHP extensions: curl, json, phar (for PHAR distribution)
• A Deskpro Cloud or On-Premise instance with one of:
  • An API key (generated by a Deskpro admin), or
  • OAuth Bearer tokens (from the Deskpro web app session)

Quick Start

PHAR (recommended)

Download the latest PHAR from Releases:

curl -LO https://pacyworld.dev/pacyworld/deskpro-mcp/releases/latest/download/deskpro-mcp.phar
chmod +x deskpro-mcp.phar

Create a config file:

mkdir -p ~/.config/deskpro-mcp
cat > ~/.config/deskpro-mcp/deskpro.json << 'EOF'
{
    "auth_method": "apikey",
    "api_token": "YOUR_API_KEY",
    "site_url": "https://yourcompany.deskpro.com"
}
EOF

Start the server:

php deskpro-mcp.phar

From Source

git clone https://pacyworld.dev/pacyworld/deskpro-mcp.git
cd deskpro-mcp
cp config/deskpro.json.sample config/deskpro.json
# Edit config/deskpro.json with your credentials
php bin/deskpro-mcp

Available Tools

Tool	Description
deskpro_get_ticket	Get ticket details by ID
deskpro_create_ticket	Create a new ticket
deskpro_update_ticket	Update ticket fields
deskpro_search_tickets	Search tickets by keyword, status, agent, department
deskpro_list_tickets	List tickets with pagination and filters
deskpro_add_reply	Reply to a ticket (visible to user)
deskpro_add_note	Add an internal agent note
deskpro_get_messages	Get messages/replies for a ticket
deskpro_assign_ticket	Assign ticket to an agent
deskpro_change_status	Change ticket status
deskpro_list_departments	List available departments
deskpro_list_agents	List agents (support staff)
deskpro_list_statuses	List ticket statuses
deskpro_get_ticket_fields	Get custom field definitions
deskpro_list_filters	List saved ticket filters/views
deskpro_list_instances	List configured Deskpro instances
deskpro_switch_instance	Switch the active default instance
deskpro_help	Context-aware help for AI agents
deskpro_tool_categories	List tool categories with descriptions
deskpro_usage_examples	Common workflow examples
deskpro_server_info	Server version, capabilities, configured instances
deskpro_error_guide	Common errors and resolution steps

All ticket, action, and lookup tools accept an optional instance parameter to target a specific Deskpro site.

Authentication

Two methods are supported. You only need one.

API Key (recommended for stability)

Requires a Deskpro admin to generate a key under Admin > Apps & Integrations > API Keys.

{
    "auth_method": "apikey",
    "api_token": "YOUR_API_KEY",
    "site_url": "https://yourcompany.deskpro.com"
}

OAuth Bearer Token

Uses JWT tokens from the Deskpro web app session. No admin access needed. Tokens refreshed on-demand when near expiry (3-hour lifetime). Tokens are stored in a separate tokens.json file (beside the config by default) that is hot-reloaded on every request - update it at any time without restarting the server.

Config (deskpro.json):

{
    "auth_method": "token",
    "site_url": "https://yourcompany.deskpro.com"
}

Token file (tokens.json, same directory):

{
    "access_token": "eyJ...",
    "refresh_token": "def502..."
}

Get tokens from your browser cookies: app_access_token and app_refresh_token (Application > Cookies in developer tools).

Warning: Close the Deskpro browser tab after extracting tokens. Deskpro rotates refresh tokens on use - if the browser refreshes while the MCP server is running, it will invalidate the server's refresh token. See SETUP.md for details.

Multi-Instance

Manage multiple Deskpro helpdesks from a single server:

{
    "default": "production",
    "instances": {
        "production": {
            "auth_method": "apikey",
            "api_token": "PROD_KEY",
            "site_url": "https://support.example.com"
        },
        "staging": {
            "auth_method": "token",
            "access_token": "eyJ...",
            "refresh_token": "def502...",
            "site_url": "https://staging.deskpro.com"
        }
    }
}

The flat (single-instance) config format shown in Quick Start is also fully supported - the instance name is derived from the site URL automatically.

IDE Integration

Windsurf

Add to your MCP configuration:

{
    "deskpro": {
        "command": "php",
        "args": ["/path/to/deskpro-mcp.phar"]
    }
}

With explicit config path:

{
    "deskpro": {
        "command": "php",
        "args": ["/path/to/deskpro-mcp.phar", "--config=/path/to/deskpro.json"]
    }
}

Other MCP Clients

Any MCP client supporting the stdio transport can use this server. Configure it to spawn php /path/to/deskpro-mcp.phar and communicate over stdin/stdout using JSON-RPC 2.0.

Configuration Locations

The server searches for deskpro.json in this order (first match wins):

1. DESKPRO_CONFIG environment variable
2. --config=/path/to/deskpro.json CLI argument
3. config/deskpro.json (relative to server root)
4. ~/.config/deskpro-mcp/deskpro.json
5. /usr/local/etc/deskpro-mcp/deskpro.json

Building from Source

Build the PHAR distribution:

php -d phar.readonly=0 bin/build-phar.php

This produces deskpro-mcp.phar (~97 KB) in the project root.

Project Structure

deskpro-mcp/
├── bin/
│   ├── deskpro-mcp              # Entry point (stdio server)
│   └── build-phar.php           # PHAR builder
├── classes/
│   └── DeskproMCP/
│       ├── DeskproClient.class.php    # HTTP client (auth, refresh, pagination)
│       └── InstanceManager.class.php  # Multi-instance registry and client factory
├── tools/
│   ├── TicketTools.php           # Ticket CRUD and search (5 tools)
│   ├── TicketActionTools.php     # Reply, note, assign, status (5 tools)
│   ├── LookupTools.php           # Departments, agents, statuses, fields, filters (5 tools)
│   ├── InstanceTools.php         # Instance list and switch (2 tools)
│   └── MetaTools.php             # Help, categories, examples, info, errors (5 tools)
├── config/
│   └── deskpro.json.sample       # Sample configuration
├── docs/
│   ├── SETUP.md                  # Full setup guide
│   ├── TOOLS.md                  # Complete tool reference
│   └── SKILL.md                  # Agent skill for AI-assisted setup
├── libraries/
│   ├── EnchiladaMCP/             # Vendored MCP library
│   └── EnchiladaHTTP/            # Vendored HTTP client
├── system/
│   ├── app.conf.php              # Application constants
│   ├── autoload.inc.php          # Class autoloader
│   └── bootstrap.inc.php         # Framework bootstrap
├── .forgejo/workflows/
│   ├── ci.yml                    # Lint + build + smoke test
│   └── release.yml               # Tagged release with PHAR upload
├── README.md
└── LICENSE                       # BSD-2-Clause

Documentation

• docs/SETUP.md - Full setup guide (both auth methods, multi-instance, IDE integration, troubleshooting)
• docs/TOOLS.md - Complete tool reference with parameter tables
• docs/SKILL.md - Agent skill for AI-assisted setup and configuration

Donations

If you find this project useful, consider a small donation:

Currency	Address
BTC	1B6eyXVRPxdEitW5vWrUnzzXUy6o38P9wN
LTC	MCrnhTAHA3n6X8jUJQj9hed5CT585sJExQ
PEPE	Pk3WZshXxi656RNNoVuZTCERVhhv4pyPJS
DOGE	DQgDGexy5tJ4StbMdyGwgfyxhcAGTRrPVB

License

BSD-2-Clause - see LICENSE.