omnom62/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.
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 . 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