zendesk_search_tickets

Instructions

Implementation Reference

• src/zendesk_mcp/tools/ticket.py:86-89 (handler)

  The MCP tool handler function for 'zendesk_search_tickets'. It accepts keyword search, status filter, and limit, then delegates to _search_tickets_data().

  @mcp.tool()
  def zendesk_search_tickets(keywords: str = "", status: str = "", limit: int = 50) -> str:
      """Search Zendesk tickets by keyword and/or status. keywords: free-text search (e.g. 'login failure LDAP'). status: new, open, pending, hold, solved, closed — leave empty for all statuses. Returns id, subject, status, requester, assignee, and dates."""
      return _search_tickets_data(keywords or None, status or None, limit)

• src/zendesk_mcp/tools/ticket.py:5-39 (helper)

  Core logic for searching tickets. Builds a Zendesk search query, iterates results, extracts ticket data (id, subject, status, priority, requester, assignee, timestamps, description), and returns JSON.

  def _search_tickets_data(keywords: str | None, status: str | None, limit: int) -> str:
      try:
          client = get_client()
          query = "type:ticket"
          if keywords:
              query += f" {keywords}"
          if status:
              query += f" status:{status}"
          results = client.search(query=query, sort_by="created_at", sort_order="desc")
          tickets = []
          for ticket in results:
              if len(tickets) >= limit:
                  break
              tickets.append({
                  "id": ticket.id,
                  "subject": ticket.subject,
                  "status": ticket.status,
                  "priority": ticket.priority,
                  "requester": {
                      "name": ticket.requester.name,
                      "email": ticket.requester.email,
                  },
                  "assignee": {
                      "name": ticket.assignee.name,
                      "email": ticket.assignee.email,
                  } if ticket.assignee else None,
                  "created_at": str(ticket.created_at),
                  "updated_at": str(ticket.updated_at),
                  "description": ticket.description[:300] if ticket.description else "",
              })
          return json.dumps(tickets, indent=2)
      except ConfigError as e:
          return str(e)
      except Exception as e:
          return f"Zendesk API error: {e}"

• src/zendesk_mcp/server.py:13-22 (registration)

  Registration: imports register_ticket_tools from ticket.py and calls it with the mcp server instance.

  from zendesk_mcp.tools.ticket import register_ticket_tools
  from zendesk_mcp.tools.comments import register_comments_tools
  from zendesk_mcp.tools.attachments import register_attachment_tools
  from zendesk_mcp.tools.gitlab_context import register_gitlab_context_tools
  from zendesk_mcp.tools.write_comments import register_write_comment_tools
  from zendesk_mcp.tools.update_ticket import register_update_ticket_tools
  from zendesk_mcp.tools.time_tracking import register_time_tracking_tools
  from zendesk_mcp.tools.git_zen import register_git_zen_tools
  
  register_ticket_tools(mcp)

• src/zendesk_mcp/tools/ticket.py:80-82 (registration)

  The decorator @mcp.tool() that registers zendesk_search_tickets (and zendesk_get_ticket) as MCP tools.

  def register_ticket_tools(mcp) -> None:
      @mcp.tool()
      def zendesk_get_ticket(ticket_id: int) -> str:

• src/zendesk_mcp/client.py:10-16 (helper)

  Helper: get_client() initializes Zendesk API client (Zenpy) used by _search_tickets_data.

  def get_client(config_file: Path | None = None) -> Zenpy:
      cfg = load_config(config_file)
      subdomain = cfg.get("subdomain", "").strip()
      token = cfg.get("oauth_token", "").strip()
      if not subdomain or not token:
          raise ConfigError("Zendesk not configured. Run: zendesk-mcp setup")
      return Zenpy(subdomain=subdomain, oauth_token=token)