Skip to main content
Glama

freshdesk-mcp

A self-hosted Model Context Protocol (MCP) server that exposes Freshdesk support data to MCP-compatible AI clients (Claude, Cursor, VS Code Copilot, etc.).

What it does

Connects your AI assistant directly to Freshdesk — search tickets, read conversations, extract text from attachments (including OCR for screenshots), and enrich results with status names, group names, and company IDs.

AI client → HTTPS POST /mcp → freshdesk-mcp → Freshdesk API
                                             → GCP Vision OCR (image attachments)

Related MCP server: libredesk-mcp

Available Tools

Tool

Description

get_ticket

Fetch a single ticket by ID. Returns status name, group name, company ID.

get_ticket_summary

Ticket + all conversations + attachments in one call.

batch_get_ticket_summaries

Multiple ticket summaries in parallel.

search_tickets

Filter by query, status, priority, type, overdue, escalated, dates, company, requester, agent, group. Full ticket history.

list_tickets

All tickets with optional filters.

get_conversations

All replies and notes for a ticket (fully paginated).

list_attachments

All attachments across ticket and conversations. Filters scanning placeholders.

get_attachment_text

Extract text from docx, xlsx, json, txt, csv, png, jpg (Vision OCR).

query_attachment

Search within a JSON attachment.

find_image_attachments

Scan multiple tickets for image attachments.

get_description_images

OCR inline images in ticket description HTML and conversation replies.

find_requester

Search contacts by name/email → requester_id.

find_company

Search companies by name → company_id.

find_agent

Search agents by name/email → agent_id. ⚠️ Requires admin API key.

list_groups

List all agent groups → group_id. ⚠️ Requires admin API key.

Note: find_agent and list_groups use Freshdesk admin-only endpoints (/api/v2/agents, /api/v2/groups). They work if your API key belongs to an admin account. Regular agent API keys will receive a 403.

Prerequisites

  • A Freshdesk account with API access

  • Docker

  • A GCP project with the Vision API enabled (optional — needed for image OCR only)

  • A container runtime — Cloud Run, AWS App Runner, Azure Container Apps, or plain Docker

Configuration

Variable

Required

Description

FRESHDESK_DOMAIN

yes

Freshdesk subdomain only — e.g. mycompany (not mycompany.freshdesk.com)

FRESHDESK_API_KEY

yes

Freshdesk API key. Find it at Profile → Profile Settings → API Key.

MCP_TOKEN

yes (HTTP mode)

Bearer token your MCP client sends in Authorization: Bearer <token>. Generate any random secret.

GCP_VISION_PROJECT

no

GCP project ID for Vision OCR. If unset, image OCR tools return an error.

MCP_TRANSPORT

no

Set to http for HTTP transport (default in the Docker image).

PORT

no

HTTP port (default 8080). Set automatically by Cloud Run.

Deployment

Docker (any platform)

# Pull pre-built image
docker pull ghcr.io/omnom62/freshdesk-mcp:latest

# Or build from source
docker build -t freshdesk-mcp .

docker run -p 8080:8080 \
  -e MCP_TRANSPORT=http \
  -e FRESHDESK_DOMAIN=mycompany \
  -e FRESHDESK_API_KEY=your-api-key \
  -e MCP_TOKEN=your-random-secret \
  -e GCP_VISION_PROJECT=my-gcp-project \
  freshdesk-mcp

GCP Cloud Run

Build and push to Artifact Registry, then deploy:

IMAGE="<region>-docker.pkg.dev/<project>/freshdesk-mcp/freshdesk-mcp"

docker build -t ${IMAGE}:latest .
DIGEST=$(docker push ${IMAGE}:latest | grep "digest:" | awk '{print $3}')

gcloud run deploy freshdesk-mcp \
  --image ${IMAGE}@${DIGEST} \
  --region <region> \
  --platform managed \
  --allow-unauthenticated \
  --set-secrets FRESHDESK_DOMAIN=FRESHDESK_DOMAIN:latest,FRESHDESK_API_KEY=FRESHDESK_API_KEY:latest,MCP_TOKEN=MCP_TOKEN:latest \
  --set-env-vars GCP_VISION_PROJECT=<project> \
  --project <project>

Store secrets in GCP Secret Manager and grant the Cloud Run runtime service account roles/secretmanager.secretAccessor on each secret.

AWS App Runner / Azure Container Apps

Deploy the Docker image to your preferred platform. Pass the configuration variables as environment variables or secrets via your platform's secret store.

Connecting your MCP client

Once deployed, add to your MCP client config:

{
  "mcpServers": {
    "freshdesk": {
      "type": "http",
      "url": "https://your-deployment-url/mcp",
      "headers": {
        "Authorization": "Bearer your-mcp-token"
      }
    }
  }
}

Secret rotation

When rotating the Freshdesk API key:

  1. Get the new key from Freshdesk → Profile → Profile Settings → API Key

  2. Verify it works: curl -s -u "<new-key>:X" "https://<domain>.freshdesk.com/api/v2/tickets?per_page=1"

  3. Update your secret store (e.g. GCP Secret Manager: echo -n "<new-key>" | gcloud secrets versions add FRESHDESK_API_KEY --data-file=- --project <project>)

  4. Redeploy to pick up the new version

Tip: Never include :X in the stored secret value — that suffix is only used in curl Basic auth syntax.

Local development

export FRESHDESK_DOMAIN=mycompany
export FRESHDESK_API_KEY=your-api-key
export MCP_TOKEN=dev-token
export GCP_VISION_PROJECT=my-gcp-project  # optional

go run .

Server starts on port 8080. MCP endpoint: POST /mcp.

License

MIT

Available Tools

15 tools
batch_get_ticket_summariesA

Fetch full summaries for multiple tickets in a single call. Each summary includes ticket details, all conversations, and attachment list. Use this instead of calling get_ticket_summary repeatedly — it fetches all tickets in parallel server-side, which is significantly faster. Typical workflow: 1. search_tickets or list_tickets → get list of ticket IDs 2. batch_get_ticket_summaries with those IDs → get all summaries at once Returns array of summaries in the same format as get_ticket_summary.

Inputs: ticket_ids (required). Returns: total, results

find_agentA

Search Freshdesk agents by name or email. Returns agent_id which can be passed to search_tickets agent_id to find tickets assigned to that agent.

Inputs: query (required). Returns: total, results

find_companyA

Search Freshdesk companies by name. Returns company_id which can be used in search_tickets to find all tickets from a specific organisation. Example: find_company query='Defence' then search_tickets company_id=.

Inputs: query (required). Returns: total, results

find_image_attachmentsA

Scan multiple tickets at once and return all image attachments (png, jpg, jpeg). Typical workflow: 1. search_tickets → get list of ticket IDs 2. find_image_attachments with those IDs → find screenshots 3. get_attachment_text on attachment_id → OCR the image

Inputs: ticket_ids (required). Returns: total, results

find_requesterA

Search Freshdesk contacts by name or email. Returns requester_id which can then be passed to search_tickets to find all tickets submitted by that person.

Inputs: query (required). Returns: total, results

get_attachment_textA

Extract text from a Freshdesk ticket attachment. Supported formats: - .docx: Word documents → plain text - .xlsx: Excel spreadsheets → tab-separated rows per sheet - .json: JSON files → pretty printed - .txt: plain text - .csv: CSV files → plain text - .png .jpg .jpeg: screenshots and images → OCR via Google Vision API Use list_attachments first to get the attachment_id. Ideal for reading investigation reports, domain lists, DNS screenshots and phishing page captures.

Inputs: ticket_id (required), attachment_id (required). Returns: name, text, attachment_id

get_conversationsA

Get all replies, notes and email threads for a Freshdesk ticket. Returns body_text (plain text, HTML stripped), incoming=true means customer sent it, incoming=false means agent sent it. Use this to understand the full investigation history, analyst notes, and customer communications.

Inputs: ticket_id (required). Returns: ticket_id, conversations

get_description_imagesA

Extract and OCR inline images embedded in a ticket's description HTML body. Some tickets contain screenshots pasted directly into the description rather than uploaded as file attachments — these are not visible via list_attachments. Use this tool when get_ticket_summary shows a non-empty description but list_attachments finds no images, or when the description mentions a screenshot/table/log. Returns OCR text from each inline image found.

Inputs: ticket_id (required). Returns: total, images, ticket_id

get_ticketA

Retrieve a single Freshdesk support ticket by its numeric ID. Returns full details including id, subject, status, type, priority, due_by, is_escalated, created_at, tags and custom_fields (cf_impact, cf_urgency, cf_category, cf_subcategory, cf_domain).

Inputs: ticket_id (required). Returns: id, tags, type, due_by, +13 more

get_ticket_summaryA

Retrieve a complete summary of a Freshdesk ticket in one call: ticket details, all conversation replies and notes, and list of attachments. Use this as the first tool when investigating a specific ticket — it gives everything needed to understand the full context without multiple round trips. Returns: - ticket: id, subject, status, type, priority, due_by, is_escalated, custom_fields - conversations: all replies and notes with body_text and direction (incoming=customer, outgoing=agent) - attachments: list of files with id, name, content_type, size (use get_attachment_text to read them)

Inputs: ticket_id (required). Returns: ticket, attachments, conversations

list_attachmentsA

List all attachments on a Freshdesk ticket including files in conversation replies. Returns attachment id, name, content_type and size in bytes. Always call this before get_attachment_text, query_attachment or find_image_attachments to discover attachment IDs.

Inputs: ticket_id (required). Returns: ticket_id, attachments

list_groupsA

List all Freshdesk agent groups. Returns group id and name. Use this to find the group_id for filtering tickets by team. Example workflow: list_groups → find "Threat Intelligence" id → search_tickets group_id= Known groups:

Returns: total, results

list_ticketsA

Return all Freshdesk tickets with full fields for reporting and analysis. All filters are optional. Filters: - status: 2=open, 3=pending, 4=resolved, 5=closed - priority: 1=low, 2=medium, 3=high, 4=urgent - type: "False Positive", "False Negative", "Service Request", "Incident" - created_after / created_before: ISO8601 e.g. "2026-06-01T00:00:00Z" Use this for bulk analysis - e.g. all false positives this month, all high priority open tickets. For company or requester filtering use search_tickets instead.

Inputs: type, status, priority, created_after, +2 more. Returns: total, results

query_attachmentB

Search within a JSON attachment on a Freshdesk ticket. Useful for finding specific domains or threat feeds in large JSON files.

Inputs: query (required), ticket_id (required), attachment_id (required). Returns: name, query, result, attachment_id

search_ticketsA

Search and filter Freshdesk tickets. All fields are optional. Filters: - query: text matched against subject or type - status: 2=open, 3=pending, 4=resolved, 5=closed - priority: 1=low, 2=medium, 3=high, 4=urgent - type: "False Positive", "False Negative", "Service Request", "Incident" - overdue: true = tickets past due_by that are still open or pending - is_escalated: true = escalated tickets only - created_after / created_before: ISO8601 date e.g. "2026-06-01T00:00:00Z" - requester_id: from find_requester tool - company_id: from find_company tool Examples: Overdue tickets: {"overdue": true} Open false positives: {"type": "False Positive", "status": 2} High priority open: {"status": 2, "priority": 3} All tickets from Defence: first call find_company query="Defence", then use company_id

Inputs: type, query, status, overdue, +9 more. Returns: total, results

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 15 tools

    Disambiguation4/5

    Most tools have distinct purposes, but search_tickets and list_tickets overlap significantly in filtering tickets. The presence of both get_ticket and get_ticket_summary, as well as batch_get_ticket_summaries, could cause confusion about which to use when.

    Naming Consistency4/5

    Naming mostly follows a verb_noun pattern (find_company, search_tickets, get_ticket, list_attachments), with minor deviations like 'query_attachment' instead of a consistent verb like 'search'. Overall consistent and predictable.

    Tool Count4/5

    15 tools is a reasonable count for a Freshdesk integration covering search, retrieval, and attachment handling. Slightly heavy but each tool adds value.

    Completeness4/5

    Covers key read operations (search, get, list) and attachment extraction, but lacks create/update/delete for tickets, which may be needed for a full lifecycle. Missing tools for modifying tickets or adding notes.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      MCP server that exposes the complete Libredesk REST API (54 endpoints) as tools, enabling natural language management of conversations, contacts, agents, teams, and more for the open-source customer support desk.
      54
      9 npm
      4
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      An MCP server implementation that integrates with Freshdesk, enabling AI models to interact with Freshdesk modules and perform various support operations.
      59
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI assistants to interact with Freshservice service desk, supporting ticket search, retrieval, and creation via a configurable, Docker-first deployment.
      MIT