Skip to main content
Glama
Tidio MCP Server

Tidio MCP Server

by adrmrn

Tidio MCP Server

A Model Context Protocol (MCP) server that integrates with the Tidio customer service platform.

It acts as a layer over the Tidio OpenAPI (REST API), making Tidio functionality available directly in LLM clients such as Claude Desktop.

Requirements

  • Tidio Account — Tidio Plus plan (or higher)

  • API Credentials — Client ID and Client Secret (see the authorization guide)

  • Environment — Docker, or Python 3.13+ with uv

Related MCP server: Gorgias MCP Server

Setup

Option 1: Non-Technical Users (Claude Desktop + Docker)

You can quickly get started using the ready-to-use Docker image adrmrn/tidio-mcp from Docker Hub.

  1. Install and run Docker Desktop

  2. Install and open Claude Desktop

  3. In Claude Desktop, go to Settings → Developer → Edit Config, and open the claude_desktop_config.json file in a text editor

  4. Add the following configuration, replacing the placeholders with your Tidio credentials:

    {
      "mcpServers": {
        "Tidio": {
          "command": "docker",
          "args": [
            "run", "-i", "--rm",
            "-e", "TIDIO_CLIENT_ID",
            "-e", "TIDIO_CLIENT_SECRET",
            "adrmrn/tidio-mcp:latest"
          ],
          "env": {
            "TIDIO_CLIENT_ID": "PASTE_YOUR_CLIENT_ID_HERE",
            "TIDIO_CLIENT_SECRET": "PASTE_YOUR_CLIENT_SECRET_HERE"
          }
        }
      }
    }
  5. Save the file and restart Claude Desktop

Option 2: Technical Users (Python)

  1. Clone this repository

  2. Install dependencies with uv sync

  3. Copy .env.example to .env and set your Tidio credentials

  4. Add the following configuration to your MCP client:

    {
      "mcpServers": {
        "Tidio": {
          "command": "uv",
          "args": [
            "--directory",
            "/absolute/path/tidio-mcp",
            "run",
            "server.py"
          ]
        }
      }
    }
  5. Restart your MCP client to apply the configuration

Available Tools

  • Get Departments

  • Get Operators

  • Get Contacts

  • Get Contact Details

  • Delete Contact

  • Get Tickets

  • Get Ticket Details

  • Create Ticket

  • Update Ticket

  • Delete Ticket

  • Unassign Ticket

  • Reply to Ticket

  • Add Internal Note to Ticket

  • Create Contact

  • Update Contact

Missing Endpoints

The following endpoints are not yet implemented but are planned for future updates:

  • Create multiple contacts (POST /contacts/batch)

  • Update multiple contacts (PATCH /contacts/batch)

  • Get viewed pages history (GET /contacts/{contact_id}/viewed-pages)

  • Get contact messages (POST /contacts/{contact_id}/messages)

Contributing

Contributions are welcome!
If you’d like to improve this project, feel free to open an issue or submit a PR.

For development, the repository includes a Makefile with handy commands to build, debug, and test the project.

Available Tools

16 tools
add_internal_note_to_a_ticketAdd internal note to a TicketA

Add an internal note to a specific ticket in Tidio. This note is only visible to operators and not sent to the customer.

Args: ticket_id (int): Required. The ID of the ticket to add a note to. content (str): Required. The content of the internal note. Must be plain text. operator_id (str): Required. The UUID of the operator who is adding the note.

Returns: Dict: A dictionary with success status and created message ID.

Raises: ValueError: If any of the provided arguments have invalid values.

Inputs: content (required), ticket_id (required), operator_id (required).

create_contactCreate ContactA

Create a new contact in Tidio. Always creates a new contact; existing data is never overwritten. At least one of email, first_name, last_name, or phone must be provided.

distinct_id is required and identifies the contact in your external system. If the user has not supplied a distinct_id, ASK them for it. Do NOT invent one or copy it from any other field — not from email, phone, name, email_consent, or any custom property.

Args: distinct_id (str): Required. ID of the contact in the external system. Maximum 55 characters. Must be a real external-system identifier provided by the user. Never copy it from email, phone, name, or any other property. Ask the user if it is missing. email (str, optional): Contact email address in RFC822 format. phone (str, optional): Contact phone number. first_name (str, optional): Contact's first name. last_name (str, optional): Contact's last name. email_consent (str, optional): Email consent status. Must be one of: 'subscribed', 'unsubscribed'. properties (list, optional): List of custom contact properties. Each item must be a dict with 'name' (max 128 chars) and 'value' (max 1000 chars) fields. Example: [{"name": "plan", "value": "premium"}, {"name": "score", "value": 42}]

Returns: Dict: A dictionary containing the created contact ID.

Raises: ValueError: If any of the provided arguments have invalid values.

Inputs: distinct_id (required), email, phone, last_name, +3 more.

create_ticketCreate TicketA

Create a new ticket in Tidio. This tool creates a ticket from a customer's perspective.

Args: contact_email (str): Required. Email of the customer creating the ticket. subject (str): Required. Subject of the ticket. message_content (str): Required. Ticket message content from the customer. assigned_department_id (str, optional): UUID of assigned department. When not provided, the General department is assigned as default.

Returns: Dict: A dictionary containing the created ticket ID.

Inputs: subject (required), contact_email (required), message_content (required), assigned_department_id.

delete_contactDelete ContactA

Delete a specific contact (customer) from Tidio.

Args: contact_id (str): Required. The UUID of the contact to delete.

Returns: Dict: A dictionary with success status.

Inputs: contact_id (required).

delete_ticketDelete TicketA

Delete a specific ticket from Tidio.

Args: ticket_id (int): Required. The ID of the ticket to delete.

Returns: Dict: A dictionary with success status.

Inputs: ticket_id (required).

get_contact_detailsGet Contact detailsA

Get details of a specific contact (customer) from Tidio.

Args: contact_id (str): Required. The UUID of the contact to retrieve.

Returns: Dict: A dictionary containing the contact details.

Inputs: contact_id (required).

get_contact_propertiesGet Contact PropertiesA

Get all contact properties from Tidio. Contact properties are fields that can be associated with contacts, including default properties (name, email, phone, etc.) and custom ones.

This endpoint supports pagination. If the response contains meta.cursor with a non-null value, there are more results available. Pass that cursor value to the next request to fetch the next page. When meta.cursor is null, you've reached the end of the list.

Args: cursor (str, optional): Pagination cursor from previous response. Use the value from meta.cursor to fetch the next page of results.

Returns: Dict: A dictionary containing contact properties and pagination metadata. Each property has: name (internal identifier), label (human-readable), and type (one of: text, number, email, phone, url).

Inputs: cursor.

get_contactsGet ContactsA

Get all contacts from Tidio. Contacts are customers that have contacted company via chat or email.

This endpoint supports pagination. If the response contains meta.cursor with a non-null value, there are more results available. Pass that cursor value to the next request to fetch the next page. When meta.cursor is null, you've reached the end of the list.

Args: cursor (str, optional): Pagination cursor from previous response. Use the value from meta.cursor to fetch the next page of results. email (str, optional): Filter contacts by email address. Must be a full, valid email address (wildcards not supported).

Returns: Dict: A dictionary containing contacts information and pagination metadata.

Inputs: email, cursor.

get_departmentsGet DepartmentsA

Get all departments from Tidio. Departments are a agent groups, and can be assigned to tickets.

Returns: Dict: A dictionary containing departments information.

Inputs: no named parameters.

get_operatorsGet OperatorsA

Get all operators from Tidio. Operators are agents that manage tickets and contact with customers. Operator can be assigned to tickets.

This endpoint supports pagination. If the response contains meta.cursor with a non-null value, there are more results available. Pass that cursor value to the next request to fetch the next page. When meta.cursor is null, you've reached the end of the list.

Args: cursor (str, optional): Pagination cursor from previous response. Use the value from meta.cursor to fetch the next page of results.

Returns: Dict: A dictionary containing operator information and pagination metadata.

Inputs: cursor.

get_ticket_detailsGet Ticket detailsA

Get details of a specific ticket from Tidio. Use this to get full ticket information including messages.

Args: ticket_id (int): Required. The ID of the ticket to retrieve.

Returns: Dict: A dictionary containing the ticket details.

Inputs: ticket_id (required).

get_ticketsGet TicketsA

Get all tickets from Tidio. Use this to get tickets overview.

This endpoint supports pagination. If the response contains meta.cursor with a non-null value, there are more results available. Pass that cursor value to the next request to fetch the next page. When meta.cursor is null, you've reached the end of the list.

Args: cursor (str, optional): Pagination cursor from previous response. Use the value from meta.cursor to fetch the next page of results.

Returns: Dict: A dictionary containing ticket information and pagination metadata.

Inputs: cursor.

reply_to_a_ticketReply to a TicketA

Send a public reply to a specific ticket in Tidio. This reply will be visible to the customer and sent to them.

Args: ticket_id (int): Required. The ID of the ticket to reply to. content (str): Required. The content of the reply. Can be HTML. operator_id (str): Required. The UUID of the operator who is sending the reply.

Returns: Dict: A dictionary with success status and created message ID.

Inputs: content (required), ticket_id (required), operator_id (required).

unassign_ticketUnassign TicketB

Unassign operator from ticket in Tidio.

Args: ticket_id (int): Required. The ID of the ticket to unassign.

Returns: Dict: A dictionary with success status.

Inputs: ticket_id (required).

update_contactUpdate ContactA

Update a specific contact in Tidio. Pass only the fields you want to update. Omitted fields remain unchanged; null clears the field (except distinct_id, which cannot be cleared).

Args: contact_id (str): Required. The UUID of the contact to update. email (str, optional): Contact email address in RFC822 format. phone (str, optional): Contact phone number. first_name (str, optional): Contact's first name. last_name (str, optional): Contact's last name. email_consent (str, optional): Email consent status. Must be one of: 'subscribed', 'unsubscribed'. distinct_id (str, optional): External system identifier. Maximum 55 characters. Cannot be cleared (null is not accepted). properties (list, optional): List of custom contact properties to update. Each item must be a dict with 'name' (max 128 chars) and 'value' (max 1000 chars) fields. Example: [{"name": "plan", "value": "premium"}, {"name": "score", "value": 42}]

Returns: Dict: A dictionary with success status.

Raises: ValueError: If any of the provided arguments have invalid values.

Inputs: contact_id (required), email, phone, last_name, +4 more.

update_ticketUpdate TicketA

Update a specific ticket from Tidio with new information.

Args: ticket_id (int): Required. The ID of the ticket to update. status (str, optional): The new status for the ticket. Must be one of: 'open', 'pending', 'solved'. priority (str, optional): The new priority for the ticket. Must be one of: 'low', 'normal', 'urgent'. assigned (dict, optional): Dictionary with 'type' and 'id' fields to assign the ticket. Example: {"type": "operator", "id": "uuid-here"} or {"type": "department", "id": "dept-uuid-here"}. 'type' must be either 'operator' or 'department'. 'id' must be a string (UUID).

Returns: Dict: A dictionary with success status.

Raises: ValueError: If any of the provided arguments have invalid values.

Inputs: ticket_id (required), status, assigned, priority.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 16 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: contacts, tickets, departments, operators, and contact properties are cleanly separated. Even similar-sounding operations like reply_to_a_ticket and add_internal_note_to_a_ticket are clearly differentiated by their public/internal nature and descriptions.

    Naming Consistency4/5

    The vast majority of tools follow a clear verb_noun pattern (get_contacts, create_ticket, delete_contact). Two exceptions, reply_to_a_ticket and add_internal_note_to_a_ticket, use longer verb-preposition phrases, which are slightly inconsistent but still predictable and readable.

    Tool Count4/5

    16 tools is just above the typical well-scoped range of 3-15, but the count feels justified for a customer support platform covering contacts, tickets, and related operational entities. There is no bloat or redundancy.

    Completeness4/5

    Contacts and tickets both have full CRUD coverage, and ticket-specific actions like replying, adding notes, and unassigning are present. Minor gaps exist, such as lack of ticket filtering or department/operator management, but these are not critical for the primary workflows.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to manage Gorgias support tickets: list open tickets, read conversation history, draft internal notes, send outbound replies (gated), and look up customer history.
      MIT