freshdesk-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@freshdesk-mcp-server Which tickets are waiting on us? Read the top one and draft a reply as an internal note."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
freshdesk-mcp-server
An MCP server for Freshdesk, built around the part every other Freshdesk integration gets wrong: knowing which tickets actually need an answer.
npx -y freshdesk-mcp-server19 tools over the Freshdesk REST API v2 — read tickets with their full thread, move fields, draft internally, reply to customers — with two opinions baked in:
Ticket status does not tell you whose turn it is. A ticket can sit in "In Progress" and still owe the customer a reply for four days. This server works that out from the reply timestamps instead of guessing from status.
Your account is not the demo account. Statuses, custom fields and their choices are discovered from your Freshdesk, never hardcoded.
Why another one
There are several Freshdesk MCP servers. This one exists because of four specific things.
The queue is computed, not guessed. GET /tickets has two defaults that individually look reasonable and together hide exactly the work you care about:
Without
updated_sinceit filters by creation date over the last 30 days. A ticket opened two months ago whose customer replied this morning is simply absent — and ordering bycreated_atburies it even when it is present.2=Open, 3=Pendingare the statuses Freshdesk ships. An account with custom statuses keeps its live work elsewhere, so filtering on the defaults returns zero tickets while looking perfectly correct.
Both are regression-tested here. freshdesk_find_unanswered_tickets asks for updated_since + order_by=updated_at, and reads include=stats to compare agent_responded_at against requester_responded_at — so classifying a whole page of 100 tickets costs no extra API call.
Nothing is hardcoded. The status codes, priorities, ticket types and custom fields come from GET /ticket_fields. You can filter and write using names ("Esperando confirmación", accents optional) and an invalid value fails locally, listing the valid ones, instead of returning an opaque 400.
It respects a shared, small budget. Freshdesk's rate limit is per account, not per key, so every integration you run draws from the same bucket — and per-endpoint ceilings are lower than the account one (ticket listing is capped at 20/min on entry plans). This server throttles client-side, honours Retry-After, reports the remaining budget in errors, and asks for per_page=100 so a result set costs the fewest possible calls.
It never hides who sees a write. Every tool says whether the customer receives an email, sees it on the portal, or never knows it happened.
Related MCP server: FS_MCP_thin
Quickstart
Get your key: Freshdesk → your avatar → Profile Settings → "Your API Key".
Claude Code
claude mcp add freshdesk \
--env FRESHDESK_DOMAIN=yourcompany.freshdesk.com \
--env FRESHDESK_API_KEY=your_key \
-- npx -y freshdesk-mcp-serverClaude Desktop, Cursor, or anything else with an mcpServers block
{
"mcpServers": {
"freshdesk": {
"command": "npx",
"args": ["-y", "freshdesk-mcp-server"],
"env": {
"FRESHDESK_DOMAIN": "yourcompany.freshdesk.com",
"FRESHDESK_API_KEY": "your_key"
}
}
}
}Then ask for the queue:
Which tickets are waiting on us? Read the top one and draft a reply as an internal note.
Configuration
Variable | Required | Default | What it does |
| yes | — |
|
| yes | — | Profile Settings → Your API Key |
| no |
| Status codes that mean "nobody is waiting on us". Read the note below |
| no |
| Client-side throttle. Lower it if other integrations share the account |
| no |
| Cap on pages walked per listing. Truncation is always reported, never silent |
| no |
| Retries on 429 and 5xx |
| no |
| Per-request timeout |
About FRESHDESK_CLOSED_STATUSES
This has to be configuration rather than detection, and it is worth 30 seconds of your attention. GET /ticket_fields lists your custom statuses with their labels but says nothing about which of them are terminal, and guessing from a label breaks the moment your account is not in English. Resolved (4) and Closed (5) are the two Freshdesk ships, so they are the default.
Run freshdesk_get_ticket_fields once and look at your statuses. If you have your own terminal state — a "Merged" or "Cancelled" — name it:
FRESHDESK_CLOSED_STATUSES=4,5,10Get this wrong and tickets nobody is waiting on will show up in the queue. An unknown status is deliberately treated as open: surfacing a ticket that needed no answer is cheap, hiding one that did is not.
Tools
Reading
Tool | What it does |
| Start here. The queue of tickets awaiting our reply, most recently prodded first |
| Recent tickets, filtered by status name or code |
| One ticket: fields, requester, company, reply timestamps, original request |
| The whole thread, each message labelled by author and visibility |
| The filter endpoint, for questions a listing cannot express |
| Your account's real statuses, priorities, types and custom fields |
| Who is asking, and for which account |
| That person's history — "have they asked this before?" |
| Parent, children and trackers, so a recurring incident stays one thing |
| The documented answer, from your solution articles |
| Wording your team already approved |
Writing
Tool | Does the customer see it? | Annotations |
| No email. Status changes are visible on the portal |
|
| Never. Internal only |
|
| Visible on the portal, no email sent |
|
| Yes — it emails them. Cannot be unsent |
|
| No |
|
Bodies accept markdown or plain text and are converted to the HTML Freshdesk expects. This matters more than it sounds: a body sent with raw \n newlines arrives in the customer's inbox as one unbroken paragraph, because Freshdesk drops the string straight into an HTML email.
Resources and prompts
freshdesk://instance/fields— your field inventory, loadable once as context instead of a tool call per session.freshdesk://instance/account— account name and plan (the plan sets your rate limits).Prompt
draft_reply— the full workflow: find what is waiting → read the thread → check history → ground it in the KB and approved wording → leave the draft where a human can approve it.Prompt
triage_ticket— read a ticket and propose field moves, with a reason for each.
Safety model
Be clear-eyed about this before you point it at a production help desk.
A Freshdesk API key is account-wide and cannot be scoped. The same key that reads tickets can close them and email your customers. The only real granularity available is the Freshdesk role of the agent who owns the key — so if you want a read-mostly setup, create a limited agent in Freshdesk and use their key. This server cannot fence off what the key can do.
Tool annotations are advisory. destructiveHint asks your MCP client to confirm before calling; a client that does not prompt will let a model act without friction. Do not treat the hints as a control.
So freshdesk_reply_to_customer is two-step. Called without confirm, it returns exactly what would be sent — recipient, subject, rendered HTML — and sends nothing:
PREVIEW — nothing was sent.
Ticket: #4821 Invoice export missing March rows
Would email: Dana Okafor <dana@example.com>
Body as Freshdesk would render it:
<p>Hi Dana,</p><p>Thanks for the update.</p>
To send this for real, call freshdesk_reply_to_customer again with confirm: true.A retried or mistaken tool call therefore costs a preview, not an email to somebody's customer.
When a human should approve the wording, do not send at all. Freshdesk has no draft concept in its API, but a private note is exactly that: the text lands on the ticket for a person to read, edit and send themselves. That is what draft_reply uses by default.
Every write is logged to stderr with a timestamp, the tool, the ticket and the size — never to stdout, which carries the MCP protocol.
The API key is never logged. It is stripped from error text before it leaves the process, because Freshdesk echoes request context into some error bodies and one leak into a client's logs means rotating a credential that opens the whole account.
Troubleshooting
401 — the key is wrong, revoked, or belongs to a different domain than FRESHDESK_DOMAIN.
403 — the key is valid but the owning agent's Freshdesk role does not allow the operation. This is a permissions change in Freshdesk, not something to retry.
429 — you hit the account-wide limit. It is shared with every other integration on the account; lower FRESHDESK_REQUESTS_PER_MINUTE. Note that each include side-load costs extra credit, so a listing is rarely one call's worth.
A filter returns nothing but the tickets clearly exist — you are almost certainly filtering on statuses your account does not use. Run freshdesk_get_ticket_fields.
Closed tickets in the queue — set FRESHDESK_CLOSED_STATUSES to include your own terminal statuses.
Resolving a ticket fails with a 400 naming a field — your account marks that field required_for_closure. freshdesk_get_ticket_fields lists which ones, and freshdesk_update_ticket warns before the call.
Why not Freshdesk's own /mcp endpoint?
Freshdesk hosts an MCP server at https://<domain>.freshdesk.com/mcp, but it is OAuth-only: it answers WWW-Authenticate: Bearer resource_metadata=… and rejects any static token with a 403. That is fine for a client that runs an interactive OAuth flow and refreshes tokens, and unusable for anything wiring up a long-lived credential. Freshdesk's REST API v2 authenticates with an API key that does not expire, which is what this server uses.
A useful diagnostic in general: before assuming a /mcp endpoint takes a token, call it with no auth and read the WWW-Authenticate header.
Development
npm install
npm run build # tsc; the bin keeps its shebang
npm test # 71 tests, no network
npm run typecheck
npm run lint # biome
npm run inspect # build + @modelcontextprotocol/inspector over stdioTests stub fetch and never touch a real Freshdesk. Three of them are regression tests for bugs that are easy to reintroduce: a custom-status account returning an empty queue, a 40-day-old ticket with a fresh customer reply being ranked below a young quiet one, and a 429 being propagated instead of retried.
One more guards the write surface. WRITE_TOOL_NAMES in src/tools/index.ts is maintained by hand, and a test compares it against the annotations the tools actually declare. Adding a mutating tool without declaring it destructive fails the suite — which is the point. A security-relevant list that is derived from another list is not a list, it is a default.
Built on @modelcontextprotocol/server v2 with Zod v4 schemas, over stdio. Node ≥ 20.
Releasing
Releases go out through npm trusted publishing (OIDC): there is no NPM_TOKEN in this
repository and no long-lived write token anywhere. release.yml exchanges a GitHub Actions
OIDC token for a short-lived credential scoped to this repo and workflow, and npm attaches a
provenance attestation automatically.
That leaves one wrinkle, worth knowing before you look for the setting: the first version of
a package cannot be published with OIDC. The trusted-publisher configuration lives on the
package's own settings page, and that page does not exist until the package does. So 0.1.0
is published by hand, once:
npm login # browser + 2FA
npm run lint && npm run typecheck && npm test && npm run build
npm publish # no --provenance: attestations need a CI OIDC contextThen, on npmjs.com → the package → Settings → Trusted Publisher:
Field | Value |
Provider | GitHub Actions |
Organization or user |
|
Repository |
|
Workflow filename |
|
Every release after that is a tag:
npm version patch # or minor / major; writes package.json and commits
git push --follow-tagsrelease.yml refuses to publish if the tag and package.json disagree, and asserts
npm >= 11.5.1 before trying — an older client cannot complete the OIDC handshake, silently
falls back to anonymous, and fails with a 404 that reads like a missing package rather than
a missing permission.
Once trusted publishing works, consider turning on "require two-factor authentication and disallow tokens" for the package. It makes this workflow the only way to publish.
License
MIT
Available Tools
19 toolsfreshdesk_add_private_noteAdd an internal note (the customer never sees it)ADestructive
Add a private note to a ticket. THE CUSTOMER NEVER SEES THIS and no email is sent.
This is where a draft reply belongs. Freshdesk has no draft concept in its API, but a private note is exactly that: the text sits on the ticket for a human to read, edit and send themselves. Prefer this over freshdesk_reply_to_customer whenever a person should approve the wording first.
Accepts markdown or plain text and converts it to the HTML Freshdesk expects, so line breaks survive.
Inputs: body (required), ticket_id (required), notify_emails.
freshdesk_add_public_noteAdd a public note (visible, but no email)ADestructive
Add a note the requester CAN see on the support portal. Freshdesk does not email a public note, so it is quieter than a reply — but it is still customer-visible and cannot be unsent.
If you want the customer to actually receive the message, use freshdesk_reply_to_customer. If a human should approve it first, use freshdesk_add_private_note.
Inputs: body (required), ticket_id (required).
freshdesk_find_unanswered_ticketsFind tickets awaiting our replyARead-only
The queue of tickets where the support team owes the customer a reply.
This is the entry point for "what do I have to answer". It does NOT trust ticket status: a ticket can sit in a custom status like "In Progress" and still owe an answer. Instead it compares, per ticket, when we last replied against when the customer last wrote. Tickets waiting on the customer are excluded, as are terminal ones.
Ordered by how recently the customer wrote, so entry #1 is the freshest thing left unanswered. Read the full thread with freshdesk_get_ticket and freshdesk_get_conversations before drafting anything.
Inputs: days, limit, pages.
freshdesk_get_articleGet one knowledge base articleBRead-only
The full body of a solution article, as markdown.
Inputs: article_id (required).
freshdesk_get_canned_responseGet one canned responseARead-only
The full body of a canned response, as markdown. Freshdesk placeholders such as {{ticket.requester.name}} are left untouched — substitute them yourself before sending.
Inputs: canned_response_id (required).
freshdesk_get_companyGet a companyARead-only
The account a contact belongs to, with its notes and custom fields. Useful for tone and for knowing how much a ticket matters.
Inputs: company_id (required).
freshdesk_get_contactGet a contactARead-only
The person behind a ticket: name, email, job title, company and any custom contact fields. Use the requester_id from a ticket.
Inputs: contact_id (required).
freshdesk_get_conversationsRead the whole thread of a ticketARead-only
Every message on a ticket, oldest first, each one labelled with who wrote it and who can see it:
CUSTOMER — the requester wrote it AGENT (public) — we wrote it and the customer received it AGENT (private) — an internal note; the customer never saw this
Two things to know before drafting from this. The ticket DESCRIPTION is the customer's first message and is not part of this list — get it from freshdesk_get_ticket. And many tickets open with an automated private note from the helpdesk itself: that is internal routing chatter, not something the customer said.
Inputs: ticket_id (required), limit, max_chars_per_message.
freshdesk_get_ticketGet one ticket with its contextARead-only
Full detail for a single ticket: fields, requester, company and reply timestamps.
The description is the customer's ORIGINAL request, converted from Freshdesk's email HTML to markdown. It is not the latest message — use freshdesk_get_conversations for the thread.
Inputs: ticket_id (required).
freshdesk_get_ticket_fieldsGet this account's statuses and custom fieldsARead-only
The real field inventory of this Freshdesk account: every status with its code and label, priorities, sources, ticket types, and every custom field with its choices.
Worth reading before filtering or writing. Accounts define their own statuses, so the Freshdesk defaults (2=Open, 3=Pending) are often nearly unused, and a filter built on them returns nothing while looking correct.
Inputs: no named parameters.
freshdesk_list_canned_responsesList the team's canned responsesARead-only
The wording the team already approved, by folder.
Reach for this before inventing a phrasing: a canned response carries the tone, the legal caveats and the escalation wording someone already decided on. Pass a folder_id to list its responses, or omit it to see the folders.
Inputs: folder_id.
freshdesk_list_requester_ticketsHistory of one requesterARead-only
Every recent ticket from the same person — the answer to "have they asked this before?".
Read this before drafting anything that explains a known issue: if the same requester already got an answer three weeks ago, repeating it differently is worse than pointing back at it.
Inputs: requester_id (required), days, limit.
freshdesk_list_ticketsList recent ticketsARead-only
List tickets by recent activity, optionally filtered by status.
Statuses are given by NAME or code and validated against this account, so you cannot silently filter on a status that does not exist. Leave "statuses" empty to get every non-terminal status.
This answers "what is going on"; for "what do I owe an answer on", use freshdesk_find_unanswered_tickets instead — reply state is not derivable from status.
Inputs: days, limit, pages, statuses.
freshdesk_log_timeLog time on a ticketADestructive
Record a time entry against a ticket. Internal bookkeeping: the customer never sees it.
Inputs: ticket_id (required), time_spent (required), note, agent_id, +1 more.
freshdesk_reply_to_customerReply to the customer (SENDS AN EMAIL)ADestructive
Send a public reply on a ticket. THIS EMAILS THE REQUESTER and cannot be unsent.
Two-step by design: called without confirm, it returns exactly what would be sent — recipients, subject line, rendered HTML — and sends nothing. Call it again with confirm: true to actually send. A retry or a mistaken tool call therefore costs a preview, not an email to somebody's customer.
If a human is supposed to approve the wording, do not use this at all: put the draft in freshdesk_add_private_note and let them send it.
Inputs: body (required), ticket_id (required), confirm, cc_emails, +2 more.
freshdesk_search_knowledgeSearch the knowledge baseARead-only
Search published solution articles by keyword, so a reply can point at the documented answer instead of paraphrasing it.
Freshdesk has no article search endpoint in the v2 API, so this walks the category/folder tree and matches titles and bodies locally. That costs several calls against the rate limit, so it caches nothing and is worth calling with a narrow term.
Inputs: term (required), limit, include_drafts.
freshdesk_search_ticketsSearch tickets with a queryARead-only
Freshdesk's filter/search endpoint, for questions a plain listing cannot express.
Query syntax: "status:3 AND priority:4", quote strings ("tag:'billing'"), dates as YYYY-MM-DD with :> and :< (>= and <=). Supported fields: agent_id, group_id, priority, status, tag, type, due_by, fr_due_by, created_at, updated_at, closed_at, plus custom fields by their cf_ name.
Hard limits from the API, not from this server: the query is capped at 512 characters, results come 30 per page, and only 10 pages are reachable — 300 results maximum. Archived tickets are excluded.
Inputs: query (required), page.
freshdesk_update_ticketChange a ticket's fieldsADestructiveIdempotent
Move a ticket: status, priority, assignee, group, type, tags, custom fields.
The customer is not emailed by this, but changing status IS visible to them on the portal, and Freshdesk automations may react to it.
Statuses and priorities are accepted by name or code and validated against this account first, so a wrong value fails here — listing the valid ones — instead of coming back as an opaque 400.
Inputs: ticket_id (required), tags, type, status, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Each tool targets a distinct resource or action. The ticket-listing tools (find_unanswered, list, search) are explicitly cross-referenced to prevent confusion, and reply/note tools are carefully separated by audience and email behavior.
All tools follow the freshdesk_verb_noun pattern consistently, using snake_case throughout. Verbs like get, list, search, add, update, reply, and log clearly indicate the action, and noun phrases are descriptive and uniform.
Nineteen tools is slightly above the ideal range, but the server covers a broad domain (tickets, contacts, companies, canned responses, knowledge base, time tracking) and each tool serves a distinct purpose without redundancy.
The server lacks a create_ticket tool, which is a core operation for a helpdesk. It also lacks tools to list contacts or companies, only fetching by ID. However, the existing read/search/reply/update flow covers most agent workflows, and these gaps can be partially worked around.
Maintenance
Related MCP Connectors
Freshdesk MCP Pack — helpdesk ticket and contact management via Freshdesk API v2.
Remote MCP server for managing Muninx tickets, messages, ticket search, and support analytics.
Customer support for MCP servers: work your tickets from Claude or any MCP client. Service key auth.
Related MCP Servers
- AlicenseCqualityDmaintenanceAn MCP server implementation that integrates with Freshdesk, enabling AI models to interact with Freshdesk modules and perform various support operations.59MIT
- AlicenseBqualityDmaintenanceA read-only MCP server that connects AI assistants to Freshservice Service Desk for ticket triage, asset analysis, and support history summarization.23ISC
- AlicenseAqualityCmaintenanceMCP server for the Ticksy support ticket API, enabling AI agents to read and write support tickets.168 npmMIT
- AlicenseBqualityDmaintenanceAn MCP server that provides operational tooling over the Zendesk Support API — ticket triage, SLA monitoring, agent workload analysis, and system health audits.111MIT