Skip to main content
Glama
freshdesk-mcp-server

freshdesk-mcp-server

by gasconc

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-server

19 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:

  1. 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.

  2. 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_since it 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 by created_at buries it even when it is present.

  • 2=Open, 3=Pending are 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-server

Claude 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

FRESHDESK_DOMAIN

yes

—

acme.freshdesk.com. A full URL or a bare acme both work

FRESHDESK_API_KEY

yes

—

Profile Settings → Your API Key

FRESHDESK_CLOSED_STATUSES

no

4,5

Status codes that mean "nobody is waiting on us". Read the note below

FRESHDESK_REQUESTS_PER_MINUTE

no

50

Client-side throttle. Lower it if other integrations share the account

FRESHDESK_MAX_PAGES

no

5

Cap on pages walked per listing. Truncation is always reported, never silent

FRESHDESK_MAX_RETRIES

no

3

Retries on 429 and 5xx

FRESHDESK_TIMEOUT_MS

no

30000

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,10

Get 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

freshdesk_find_unanswered_tickets

Start here. The queue of tickets awaiting our reply, most recently prodded first

freshdesk_list_tickets

Recent tickets, filtered by status name or code

freshdesk_get_ticket

One ticket: fields, requester, company, reply timestamps, original request

freshdesk_get_conversations

The whole thread, each message labelled by author and visibility

freshdesk_search_tickets

The filter endpoint, for questions a listing cannot express

freshdesk_get_ticket_fields

Your account's real statuses, priorities, types and custom fields

freshdesk_get_contact · freshdesk_get_company

Who is asking, and for which account

freshdesk_list_requester_tickets

That person's history — "have they asked this before?"

freshdesk_get_related_tickets

Parent, children and trackers, so a recurring incident stays one thing

freshdesk_search_knowledge · freshdesk_get_article

The documented answer, from your solution articles

freshdesk_list_canned_responses · freshdesk_get_canned_response

Wording your team already approved

Writing

Tool

Does the customer see it?

Annotations

freshdesk_update_ticket

No email. Status changes are visible on the portal

destructive, idempotent

freshdesk_add_private_note

Never. Internal only

destructive

freshdesk_add_public_note

Visible on the portal, no email sent

destructive

freshdesk_reply_to_customer

Yes — it emails them. Cannot be unsent

destructive, openWorld

freshdesk_log_time

No

destructive

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 stdio

Tests 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 context

Then, on npmjs.com → the package → Settings → Trusted Publisher:

Field

Value

Provider

GitHub Actions

Organization or user

gasconc

Repository

freshdesk-mcp-server

Workflow filename

release.yml — filename only, case-sensitive, no path

Every release after that is a tag:

npm version patch    # or minor / major; writes package.json and commits
git push --follow-tags

release.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 tools
freshdesk_add_private_noteAdd an internal note (the customer never sees it)A
Destructive

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)A
Destructive

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 replyA
Read-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 articleB
Read-only

The full body of a solution article, as markdown.

Inputs: article_id (required).

freshdesk_get_canned_responseGet one canned responseA
Read-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 companyA
Read-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 contactA
Read-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 ticketA
Read-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 contextA
Read-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 fieldsA
Read-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 responsesA
Read-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 requesterA
Read-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 ticketsA
Read-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 ticketA
Destructive

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)A
Destructive

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 baseA
Read-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 queryA
Read-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 fieldsA
DestructiveIdempotent

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

    A3.9/5.0

    Scored across 19 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • 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
      B
      quality
      D
      maintenance
      A read-only MCP server that connects AI assistants to Freshservice Service Desk for ticket triage, asset analysis, and support history summarization.
      23
      ISC
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for the Ticksy support ticket API, enabling AI agents to read and write support tickets.
      16
      8 npm
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that provides operational tooling over the Zendesk Support API — ticket triage, SLA monitoring, agent workload analysis, and system health audits.
      11
      1
      MIT