freshdesk-mcp
Provides image OCR capabilities via Google Cloud Vision API, enabling text extraction from image attachments such as screenshots.
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 |
| Fetch a single ticket by ID. Returns status name, group name, company ID. |
| Ticket + all conversations + attachments in one call. |
| Multiple ticket summaries in parallel. |
| Filter by query, status, priority, type, overdue, escalated, dates, company, requester, agent, group. Full ticket history. |
| All tickets with optional filters. |
| All replies and notes for a ticket (fully paginated). |
| All attachments across ticket and conversations. Filters scanning placeholders. |
| Extract text from docx, xlsx, json, txt, csv, png, jpg (Vision OCR). |
| Search within a JSON attachment. |
| Scan multiple tickets for image attachments. |
| OCR inline images in ticket description HTML and conversation replies. |
| Search contacts by name/email → requester_id. |
| Search companies by name → company_id. |
| Search agents by name/email → agent_id. ⚠️ Requires admin API key. |
| List all agent groups → group_id. ⚠️ Requires admin API key. |
Note:
find_agentandlist_groupsuse 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 |
| yes | Freshdesk subdomain only — e.g. |
| yes | Freshdesk API key. Find it at Profile → Profile Settings → API Key. |
| yes (HTTP mode) | Bearer token your MCP client sends in |
| no | GCP project ID for Vision OCR. If unset, image OCR tools return an error. |
| no | Set to |
| no | HTTP port (default |
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-mcpGCP 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:
Get the new key from Freshdesk → Profile → Profile Settings → API Key
Verify it works:
curl -s -u "<new-key>:X" "https://<domain>.freshdesk.com/api/v2/tickets?per_page=1"Update your secret store (e.g. GCP Secret Manager:
echo -n "<new-key>" | gcloud secrets versions add FRESHDESK_API_KEY --data-file=- --project <project>)Redeploy to pick up the new version
Tip: Never include
:Xin 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 toolsbatch_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
Scored across 15 tools
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 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.
15 tools is a reasonable count for a Freshdesk integration covering search, retrieval, and attachment handling. Slightly heavy but each tool adds value.
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
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Security-first WordPress MCP server. 129 tools for Claude, ChatGPT, Gemini. Free on wp.org.
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP server created for Freshservice, allowing AI models to interact with Freshservice modules5939MIT
- AlicenseCqualityDmaintenanceMCP 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.549 npm4MIT
- AlicenseCqualityDmaintenanceAn MCP server implementation that integrates with Freshdesk, enabling AI models to interact with Freshdesk modules and perform various support operations.59MIT
- AlicenseNot gradedqualityDmaintenanceAn 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